home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d11 / fgl10_b.arc / REF.TXT < prev    next >
Text File  |  1991-05-31  |  168KB  |  10,410 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9. Fastgraph (tm)
  10.  
  11. Reference Manual
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.                                                             Copyright (c) 1991
  51.                                                            All Rights Reserved
  52.  
  53.  
  54.  
  55.                                                            Ted Gruber Software
  56.                                                                   PO Box 13408
  57.                                                           Las Vegas, NV  89112
  58.  
  59.                                                                 (702) 735-1980
  60. Copyright (c) 1991 by Ted Gruber Software.
  61.  
  62. All rights reserved.  This publication and its associated software are sold
  63. without warranties, either expressed or implied, regarding their
  64. merchantability or fitness for any particular application or purpose.  The
  65. information in this publication is subject to change without notice and does
  66. not represent a commitment on the part of Ted Gruber Software.  In no event
  67. shall Ted Gruber Software be liable for any loss of profit or any other
  68. commercial damage, including but not limited to special, incidental,
  69. consequential, or other damages resulting from the use of or the inability to
  70. use this product, even if Ted Gruber Software has been notified of the
  71. possibility of such damages.
  72.  
  73.  
  74. First Printing, June 1991
  75.  
  76. Fastgraph version 2.00
  77. Fastgraph/Light version 1.00
  78.  
  79.  
  80.  
  81.  
  82. Fastgraph and Fastgraph/Light are trademarks of Ted Gruber Software.
  83.  
  84. Hercules is a trademark of Hercules Computer Technology.
  85.  
  86. IBM, IBM PC, IBM PC/XT, IBM PC/AT, PS/2, PCjr, and PC-DOS are
  87. registered trademarks of International Business Machines, Inc.
  88.  
  89. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.
  90.  
  91. QuickBASIC is a trademark of Microsoft Corporation.
  92.  
  93. Tandy is a registered trademark of Tandy Corporation.
  94.  
  95.  
  96.  
  97. All other brand and product names mentioned in this publication are
  98. trademarks or registered trademarks of their respective holders.
  99.                       T a b l e   o f   C o n t e n t s
  100.  
  101.  
  102. Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    1
  103.  
  104. Fastgraph Routines by Category  . . . . . . . . . . . . . . . . . . . . .    1
  105.  
  106. Alphabetical List of Fastgraph Routines . . . . . . . . . . . . . . . . .    2
  107.      fg_allocate  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    4
  108.      fg_automode  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    5
  109.      fg_bestmode  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  110.      fg_button  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  111.      fg_capslock  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
  112.      fg_chgattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
  113.      fg_chgtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
  114.      fg_circle  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
  115.      fg_circlew . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  116.      fg_clipmask  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
  117.      fg_clpimage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
  118.      fg_clprect . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
  119.      fg_clprectw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
  120.      fg_cursor  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
  121.      fg_dash  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
  122.      fg_dashrel . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
  123.      fg_dashrw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
  124.      fg_dashw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
  125.      fg_defcolor  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
  126.      fg_dispfile  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23
  127.      fg_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   24
  128.      fg_displayp  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   26
  129.      fg_draw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   28
  130.      fg_drawmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   29
  131.      fg_drawmask  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   30
  132.      fg_drawrel . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   32
  133.      fg_drawrw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   33
  134.      fg_draww . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   34
  135.      fg_drect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   35
  136.      fg_drectw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   36
  137.      fg_drwimage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   37
  138.      fg_egacheck  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   38
  139.      fg_ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   39
  140.      fg_ellipsew  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   40
  141.      fg_erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   41
  142.      fg_fadein  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   42
  143.      fg_fadeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   43
  144.      fg_flipmask  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   44
  145.      fg_flpimage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   45
  146.      fg_freepage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   46
  147.      fg_getaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   47
  148.      fg_getclock  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   48
  149.      fg_getcolor  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   49
  150.      fg_gethpage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   50
  151.      fg_getimage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   51
  152.      fg_getindex  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   52
  153.      fg_getkey  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   53
  154.      fg_getmap  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   54
  155.      fg_getmaxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   55
  156.  
  157.      fg_getmaxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   56
  158.      fg_getmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   57
  159.      fg_getpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   58
  160.      fg_getpixel  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   59
  161.      fg_getrgb  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   60
  162.      fg_getvpage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   61
  163.      fg_getworld  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   62
  164.      fg_getxjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   63
  165.      fg_getxpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   64
  166.      fg_getyjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   65
  167.      fg_getypos . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   66
  168.      fg_hush  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   67
  169.      fg_hushnext  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   68
  170.      fg_initjoy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   69
  171.      fg_initw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   70
  172.      fg_intjoy  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   71
  173.      fg_intkey  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   73
  174.      fg_locate  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   74
  175.      fg_measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   75
  176.      fg_memavail  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  177.      fg_mousebut  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   77
  178.      fg_mousecur  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   78
  179.      fg_mouseini  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   80
  180.      fg_mouselim  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   81
  181.      fg_mousemov  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   82
  182.      fg_mousepos  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   83
  183.      fg_mouseptr  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   84
  184.      fg_mousespd  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   86
  185.      fg_mousevis  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   87
  186.      fg_move  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   88
  187.      fg_moverel . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   89
  188.      fg_moverw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   90
  189.      fg_movew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   91
  190.      fg_music . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   92
  191.      fg_musicb  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   94
  192.      fg_numlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   95
  193.      fg_paint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   96
  194.      fg_paintw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   97
  195.      fg_palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  196.      fg_palettes  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  197.      fg_pan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  101
  198.      fg_panw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  102
  199.      fg_pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  103
  200.      fg_playing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  105
  201.      fg_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  106
  202.      fg_pointw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  107
  203.      fg_polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  108
  204.      fg_polygonw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  109
  205.      fg_quiet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  110
  206.      fg_rect  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  111
  207.      fg_rectw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  112
  208.      fg_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  113
  209.      fg_restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  114
  210.      fg_restorew  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  115
  211.      fg_revimage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  116
  212.      fg_revmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  117
  213.      fg_save  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  118
  214.  
  215.      fg_savew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  119
  216.      fg_scrlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  120
  217.      fg_scroll  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  121
  218.      fg_setangle  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  123
  219.      fg_setattr . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  124
  220.      fg_setcaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  125
  221.      fg_setclip . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  126
  222.      fg_setclipw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  127
  223.      fg_setcolor  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  224.      fg_setfunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  129
  225.      fg_sethpage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  130
  226.      fg_setmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  131
  227.      fg_setnum  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  133
  228.      fg_setpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  134
  229.      fg_setratio  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  135
  230.      fg_setrgb  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  136
  231.      fg_setsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  137
  232.      fg_setsizew  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  138
  233.      fg_setvpage  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  139
  234.      fg_setworld  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  140
  235.      fg_sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  141
  236.      fg_sounds  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  142
  237.      fg_stall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  144
  238.      fg_swchar  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  145
  239.      fg_swlength  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  147
  240.      fg_swtext  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  148
  241.      fg_tcmask  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  150
  242.      fg_tcxfer  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  151
  243.      fg_testmode  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  153
  244.      fg_text  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  154
  245.      fg_transfer  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  155
  246.      fg_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  157
  247.      fg_voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  158
  248.      fg_voices  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  160
  249.      fg_waitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  162
  250.      fg_waitkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  163
  251.      fg_where . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  164
  252.      fg_xalpha  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  165
  253.      fg_xconvert  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  166
  254.      fg_xscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  167
  255.      fg_xworld  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  168
  256.      fg_yalpha  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  169
  257.      fg_yconvert  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  170
  258.      fg_yscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  171
  259.      fg_yworld  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
  260.  
  261. Introduction
  262.  
  263.      The Fastgraph Reference Manual is a companion publication to the
  264. Fastgraph User's Guide.  Whereas the latter publication is essentially a
  265. detailed tutorial about Fastgraph, the Fastgraph Reference Manual is intended
  266. as a reference for programmers familiar with the product.
  267.  
  268.      This manual has two major parts.  The first part lists the Fastgraph
  269. routines by category; each category corresponds to a chapter in the Fastgraph
  270. User's Guide.  The second part, which occupies the larger portion of this
  271. manual, gives descriptions of each Fastgraph routine in alphabetical order.
  272.  
  273.  
  274. Fastgraph Routines by Category
  275.  
  276.      This section lists the Fastgraph routines by category.  These categories
  277. parallel the chapters in the Fastgraph User's Guide.  The lists in this
  278. section are provided as a general overview of Fastgraph's capabilities.  You
  279. can find detailed information about each Fastgraph routine in the next
  280. section of this manual, and of course in the Fastgraph User's Guide.
  281.  
  282. Video Initialization Routines:  fg_automode, fg_bestmode, fg_cursor,
  283. fg_egacheck, fg_getmode, fg_reset, fg_setmode, fg_testmode.
  284.  
  285. Coordinate Routines:  fg_getmaxx, fg_getmaxy, fg_getworld, fg_initw,
  286. fg_setworld, fg_xalpha, fg_xconvert, fg_xscreen, fg_xworld, fg_yalpha,
  287. fg_yconvert, fg_yscreen, fg_yworld.
  288.  
  289. Color-Related Routines:  fg_defcolor, fg_getcolor, fg_getindex, fg_getrgb,
  290. fg_palette, fg_palettes, fg_setattr, fg_setcolor, fg_setrgb.
  291.  
  292. Fundamental Graphics Routines:  fg_circle, fg_circlew, fg_clprect,
  293. fg_clprectw, fg_dash, fg_dashrel, fg_dashrw, fg_dashw, fg_draw, fg_drawrel,
  294. fg_drawrw, fg_draww, fg_drect, fg_drectw, fg_ellipse, fg_ellipsew, fg_erase,
  295. fg_getpixel, fg_getxpos, fg_getypos, fg_move, fg_moverel, fg_moverw,
  296. fg_movew, fg_paint, fg_paintw, fg_point, fg_pointw, fg_polygon, fg_polygonw,
  297. fg_rect, fg_rectw, fg_setclip, fg_setclipw.
  298.  
  299. Character Display Routines:  fg_chgattr, fg_chgtext, fg_locate, fg_setangle,
  300. fg_setattr, fg_setcolor, fg_setratio, fg_setsize, fg_setsizew, fg_swchar,
  301. fg_swlength, fg_swtext, fg_text, fg_where, fg_xalpha, fg_xconvert, fg_yalpha,
  302. fg_yconvert.
  303.  
  304. Video Page Management Routines:  fg_allocate, fg_freepage, fg_getaddr,
  305. fg_gethpage, fg_getpage, fg_getvpage, fg_sethpage, fg_setpage, fg_setvpage.
  306.  
  307. Image Management Routines:  fg_clipmask, fg_clpimage, fg_dispfile,
  308. fg_display, fg_displayp, fg_drawmap, fg_drawmask, fg_drwimage, fg_flipmask,
  309. fg_flpimage, fg_getimage, fg_getmap, fg_pattern, fg_restore, fg_restorew,
  310. fg_revimage, fg_revmask, fg_save, fg_savew, fg_tcmask, fg_tcxfer,
  311. fg_transfer.
  312.  
  313. Special Effects Routines:  fg_fadein, fg_fadeout, fg_pan, fg_panw, fg_scroll.
  314.  
  315. Input Routines:  fg_button, fg_capslock, fg_getkey, fg_getxjoy, fg_getyjoy,
  316. fg_initjoy, fg_intjoy, fg_intkey, fg_mousebut, fg_mousecur, fg_mouseini,
  317.  
  318.  
  319.                                       1
  320. fg_mouselim, fg_mousemov, fg_mousepos, fg_mouseptr, fg_mousespd, fg_mousevis,
  321. fg_numlock, fg_scrlock, fg_setcaps, fg_setnum, fg_waitkey.
  322.  
  323. Sound Routines:  fg_hush, fg_hushnext, fg_music, fg_musicb, fg_playing,
  324. fg_quiet, fg_sound, fg_sounds, fg_voice, fg_voices.
  325.  
  326. Timing Routines:  fg_getclock, fg_measure, fg_stall, fg_waitfor.
  327.  
  328. Miscellaneous Routines:  fg_memavail, fg_setfunc, fg_version.
  329.  
  330.  
  331. Alphabetical List of Fastgraph Routines
  332.  
  333.      This section presents a detailed description of each Fastgraph routine.
  334. Once you're familiar with Fastgraph, you'll probably refer to these
  335. descriptions more often than any other section of the two Fastgraph
  336. publications.
  337.  
  338.      The information presented for each routine includes the following:
  339.  
  340.      a function prototype for the C programming language
  341.      a description of the routine itself
  342.      the number of parameters, their purpose, and their data types
  343.      the meaning and data type of the routine's return value (if any)
  344.      information about important restrictions pertaining to the routine
  345.      references to similar routines, or other routines that affect the routine
  346.      example programs in the Fastgraph User's Guide that use the routine
  347.  
  348.      The C function prototype includes information about the routine's return
  349. value, the number of parameters the routine expects, and their data types.
  350. To C programmers, these prototypes should look very familiar, but if you're a
  351. QuickBASIC or FORTRAN programmer not acquainted with C, a few examples might
  352. be helpful.
  353.  
  354.      Here is the function prototype for the fg_allocate routine:
  355.  
  356.  
  357.                       int fg_allocate (int page_number);
  358.  
  359.  
  360. The int before the routine name means it returns an integer value.  This
  361. corresponds to the QuickBASIC integer or FORTRAN INTEGER*2 data type.
  362. Because the routine returns a value, you would call it as a FUNCTION.  The
  363. int page_number means the routine expects one integer parameter (named
  364. page_number) passed by value.  If the routine did not expect any parameters,
  365. the word void would appear between the parentheses.
  366.  
  367.      The function prototype for the fg_drwimage routine illustrates some
  368. additional features:
  369.  
  370.  
  371.           void fg_drwimage (char *map_array, int width, int height);
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.                                       2
  379.  
  380. The void before the routine name indicates this routine has no return value.
  381. Thus, in QuickBASIC your would call it as a SUB, and in FORTRAN as a
  382. SUBROUTINE.  The parameter list shows three items, one of type char and two
  383. of type int.  The asterisk (*) appearing before the name of the first
  384. parameter means it is passed by reference instead of by value (however, the
  385. DECLARE commands in the file FASTGRAF.BI and the INTERFACE statements in the
  386. file INTRFACE.FOR automatically account for the differences between passing
  387. parameters by reference and passing by value).
  388.  
  389.      The following table lists the C data types that Fastgraph uses for
  390. parameters and return values, along with their QuickBASIC and FORTRAN
  391. equivalents.
  392.  
  393.  
  394.            C data type  QuickBASIC equivalent  FORTRAN equivalent
  395.  
  396.            char         string                 INTEGER*1 or
  397.                                                CHARACTER*(*)
  398.            int          integer                INTEGER*2
  399.            long         long integer           INTEGER*4
  400.            double       double precision       REAL*8
  401.  
  402.      Any data types prefixed with the unsigned keyword, such as unsigned
  403. char, can generally be treated as the data type itself in QuickBASIC and
  404. FORTRAN.  In other words, unsigned char is the same as char from the
  405. QuickBASIC and FORTRAN perspectives.  Additionally, the DECLARE commands in
  406. the file FASTGRAF.BI (which must be included in QuickBASIC programs that call
  407. Fastgraph routines) and the INTERFACE statements in the file INTRFACE.FOR
  408. (which must be included in FORTRAN programs that call Fastgraph routines)
  409. automatically convert QuickBASIC and FORTRAN floating point constants to the
  410. C double data type.  This means you don't have to pass double precision
  411. constants when calling Fastgraph routines that require floating point
  412. parameters.  The INTERFACE statements also determine whether char parameters
  413. are passed from FORTRAN as INTEGER*1 or CHARACTER quantities.
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.                                       3
  439. fg_allocate
  440.  
  441.  
  442. Prototype
  443.  
  444.    int fg_allocate (int page_number);
  445.  
  446. Description
  447.  
  448.    The fg_allocate routine creates a virtual video page.  The amount of memory
  449.    required depends on the current video mode.
  450.  
  451. Parameters
  452.  
  453.    page_number is the number by which the virtual page will be referenced.  It
  454.    must be between 0 and 15.
  455.  
  456. Return value
  457.  
  458.    A status code indicating the success or failure of the virtual page
  459.    creation, as shown below.
  460.  
  461.      0 = virtual page created
  462.      7 = virtual page created, but memory control blocks were destroyed
  463.      8 = insufficient memory to create the virtual page
  464.  
  465. Restrictions
  466.  
  467.    This routine has no effect if page_number references a physical video page,
  468.    or if used in a video mode that does not support virtual video pages.
  469.  
  470. See also
  471.  
  472.    fg_freepage
  473.  
  474. Examples
  475.  
  476.    8-3, 8-4, 8-5, 8-6, 8-8, 9-21, 9-22, 9-23, 10-4, 10-5, 11-2, 11-5, 15-1
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.                                       4
  498. fg_automode
  499.  
  500.  
  501. Prototype
  502.  
  503.    int fg_automode (void);
  504.  
  505. Description
  506.  
  507.    The fg_automode routine determines the graphics video mode that offers the
  508.    most features for the user's display and adapter configuration.
  509.  
  510. Parameters
  511.  
  512.    none
  513.  
  514. Return value
  515.  
  516.    The return value is the proposed video mode number.  The current display
  517.    and adapter configuration determine the mode number, as illustrated in the
  518.    following table.
  519.  
  520.  
  521.                                          display
  522.                        adapter   mono   RGB   ECD   VGA
  523.  
  524.                           MDA       7     0     7     7
  525.                           HGC      11     0     0    11
  526.                           CGA       0     4     0     0
  527.                           EGA      15    13    16     0
  528.                           VGA      17    17    17    18
  529.                          MCGA      17    17    17    19
  530.                         Tandy       7     9     0     0
  531.                          PCjr       7     9     0     0
  532.  
  533.  
  534.    The return value can either be passed directly to the fg_setmode routine,
  535.    or it can help determine suitable video modes for your program.
  536.  
  537. Restrictions
  538.  
  539.    none
  540.  
  541. See also
  542.  
  543.    fg_bestmode, fg_setmode, fg_testmode
  544.  
  545. Examples
  546.  
  547.    3-6, 4-3
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.                                       5
  557. fg_bestmode
  558.  
  559.  
  560. Prototype
  561.  
  562.    int fg_bestmode (int horizontal, int vertical, int pages);
  563.  
  564. Description
  565.  
  566.    The fg_bestmode routine determines the video mode having the requested
  567.    resolution and the most features for the user's display and adapter
  568.    configuration.  It is similar to fg_automode, but it excludes video modes
  569.    that do not offer the specified resolution and video page requirements.
  570.    The video pages can include physical pages, virtual pages, or both.
  571.  
  572. Parameters
  573.  
  574.    horizontal specifies the required horizontal resolution.
  575.  
  576.    vertical specifies the required vertical resolution.
  577.  
  578.    pages specifies the required number of video pages.
  579.  
  580. Return value
  581.  
  582.    If fg_bestmode finds a video mode that offers the specified resolution and
  583.    video page requirements, it returns the corresponding video mode number.
  584.    If not, it returns -1.
  585.  
  586. Restrictions
  587.  
  588.    none
  589.  
  590. See also
  591.  
  592.    fg_automode, fg_setmode, fg_testmode
  593.  
  594. Examples
  595.  
  596.    3-4, 3-7
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.                                       6
  616. fg_button
  617.  
  618.  
  619. Prototype
  620.  
  621.    int fg_button (int n);
  622.  
  623. Description
  624.  
  625.    The fg_button routine returns information about the state of either
  626.    joystick's button status.
  627.  
  628. Parameters
  629.  
  630.    n specifies the joystick number, either 1 or 2.
  631.  
  632. Return value
  633.  
  634.    A status code indicating the current button status for the requested
  635.    joystick, as shown below.
  636.  
  637.      0 = neither button pressed
  638.      1 = top button pressed
  639.      2 = bottom button pressed
  640.      3 = top and bottom buttons pressed
  641.  
  642. Restrictions
  643.  
  644.    none
  645.  
  646. See also
  647.  
  648.    fg_getxjoy, fg_getyjoy, fg_initjoy, fg_intjoy
  649.  
  650. Examples
  651.  
  652.    12-11
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.                                       7
  675. fg_capslock
  676.  
  677.  
  678. Prototype
  679.  
  680.    int fg_capslock (void);
  681.  
  682. Description
  683.  
  684.    The fg_capslock routine determines the state of the CapsLock key.
  685.  
  686. Parameters
  687.  
  688.    none
  689.  
  690. Return value
  691.  
  692.    If the return value is 0, it means the CapsLock key is off.  If it is 1, it
  693.    means the CapsLock key is on.
  694.  
  695. Restrictions
  696.  
  697.    none
  698.  
  699. See also
  700.  
  701.    fg_numlock, fg_scrlock, fg_setcaps, fg_setnum
  702.  
  703. Examples
  704.  
  705.    12-3
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.                                       8
  734. fg_chgattr
  735.  
  736.  
  737. Prototype
  738.  
  739.    void fg_chgattr (int n);
  740.  
  741. Description
  742.  
  743.    The fg_chgattr routine applies the current text attribute to a given number
  744.    of characters, starting at the text cursor position.  This routine leaves
  745.    the text cursor one column to the right of the last character changed (or
  746.    the first column of the next row if the last character is at the end of a
  747.    row).
  748.  
  749. Parameters
  750.  
  751.    n is the number of characters for which to change the text attribute.
  752.  
  753. Return value
  754.  
  755.    none
  756.  
  757. Restrictions
  758.  
  759.    This routine has no effect in graphics video modes.
  760.  
  761. See also
  762.  
  763.    fg_chgtext, fg_text
  764.  
  765. Examples
  766.  
  767.    7-3
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.                                       9
  793. fg_chgtext
  794.  
  795.  
  796. Prototype
  797.  
  798.    void fg_chgtext (char *string, int n);
  799.  
  800. Description
  801.  
  802.    The fg_chgtext routine displays a string of hardware characters, starting
  803.    at the text cursor position, using the existing text attributes.  This
  804.    routine leaves the text cursor one column to the right of the last
  805.    character changed (or the first column of the next row if the last
  806.    character is at the end of a row).
  807.  
  808. Parameters
  809.  
  810.    string is the arbitrary-length sequence of characters to display.
  811.  
  812.    n is the number of characters in string.
  813.  
  814. Return value
  815.  
  816.    none
  817.  
  818. Restrictions
  819.  
  820.    This routine has no effect in graphics video modes.
  821.  
  822. See also
  823.  
  824.    fg_chgattr, fg_text
  825.  
  826. Examples
  827.  
  828.    7-3
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.                                       10
  852. fg_circle
  853.  
  854.  
  855. Prototype
  856.  
  857.    void fg_circle (int radius);
  858.  
  859. Description
  860.  
  861.    The fg_circle routine draws an unfilled circle in screen space.  The circle
  862.    is centered at the current graphics cursor position.
  863.  
  864. Parameters
  865.  
  866.    radius defines the circle's radius in horizontal screen space units.  Its
  867.    value must be greater than zero.
  868.  
  869. Return value
  870.  
  871.    none
  872.  
  873. Restrictions
  874.  
  875.    This routine has no effect in text video modes.
  876.  
  877. See also
  878.  
  879.    fg_circlew, fg_ellipse, fg_ellipsew
  880.  
  881. Examples
  882.  
  883.    6-9
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.                                       11
  911. fg_circlew
  912.  
  913.  
  914. Prototype
  915.  
  916.    void fg_circlew (double x, double y);
  917.  
  918. Description
  919.  
  920.    The fg_circlew routine draws an unfilled circle in world space.  The circle
  921.    is centered at the current graphics cursor position.
  922.  
  923. Parameters
  924.  
  925.    radius defines the circle's radius in horizontal world space units.  Its
  926.    value must be greater than zero.
  927.  
  928. Return value
  929.  
  930.    none
  931.  
  932. Restrictions
  933.  
  934.    This routine is not available in Fastgraph/Light and has no effect in text
  935.    video modes.
  936.  
  937. See also
  938.  
  939.    fg_circle, fg_ellipse, fg_ellipsew
  940.  
  941. Examples
  942.  
  943.    6-8
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.                                       12
  970. fg_clipmask
  971.  
  972.  
  973. Prototype
  974.  
  975.    void fg_clipmask (char *map_array, int runs, int width);
  976.  
  977. Description
  978.  
  979.    The fg_clipmask routine displays a clipped image stored as a masking map.
  980.    The image will be positioned so that its lower left corner is at the
  981.    graphics cursor position.  Refer to the description of the fg_drawmask
  982.    routine for more information about masking maps.
  983.  
  984. Parameters
  985.  
  986.    map_array is the arbitrary-length array containing the masking map.
  987.  
  988.    runs is the number of pixel runs in the masking map.
  989.  
  990.    width is the width in pixels of the masking map.
  991.  
  992. Return value
  993.  
  994.    none
  995.  
  996. Restrictions
  997.  
  998.    This routine has no effect in text video modes, or in the native EGA and
  999.    VGA graphics video modes.
  1000.  
  1001. See also
  1002.  
  1003.    fg_drawmask, fg_flipmask, fg_revmask, fg_setclip
  1004.  
  1005. Examples
  1006.  
  1007.    9-15
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.                                       13
  1029. fg_clpimage
  1030.  
  1031.  
  1032. Prototype
  1033.  
  1034.    void fg_clpimage (char *map_array, int width, int height);
  1035.  
  1036. Description
  1037.  
  1038.    The fg_clpimage routine displays a clipped image stored as a mode-specific
  1039.    bit map.  The image will be positioned so that its lower left corner is at
  1040.    the graphics cursor position.  Only that part of the image that falls
  1041.    within the current clipping limits will be displayed, but the clipping
  1042.    limits will be extended to a byte boundary if necessary.  Refer to the
  1043.    Fastgraph User's Guide for complete information about mode-specific bit
  1044.    maps.
  1045.  
  1046. Parameters
  1047.  
  1048.    map_array is the arbitrary-length array containing the bit map.  For EGA
  1049.    and VGA graphics modes, each color must be in a separate bit map.  For all
  1050.    other graphics modes, all colors are in a single bit map.
  1051.  
  1052.    width is the width in bytes of the bit map.
  1053.  
  1054.    height is the height in bytes (pixel rows) of the bit map.
  1055.  
  1056. Return value
  1057.  
  1058.    none
  1059.  
  1060. Restrictions
  1061.  
  1062.    This routine has no effect in text video modes.
  1063.  
  1064. See also
  1065.  
  1066.    fg_drwimage, fg_flpimage, fg_getimage, fg_revimage, fg_setclip
  1067.  
  1068. Examples
  1069.  
  1070.    9-8, 9-9
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.                                       14
  1088. fg_clprect
  1089.  
  1090.  
  1091. Prototype
  1092.  
  1093.    void fg_clprect (int minx, int maxx, int miny, int maxy);
  1094.  
  1095. Description
  1096.  
  1097.    The fg_clprect routine draws a solid (filled) rectangle in screen space,
  1098.    with respect to the clipping region.
  1099.  
  1100. Parameters
  1101.  
  1102.    minx is the screen space x coordinate of the rectangle's left edge.
  1103.  
  1104.    maxx is the screen space x coordinate of the rectangle's right edge.  It
  1105.    must be greater than or equal to the value of minx.
  1106.  
  1107.    miny is the screen space y coordinate of the rectangle's top edge.
  1108.  
  1109.    maxy is the screen space y coordinate of the rectangle's bottom edge.  It
  1110.    must be greater than or equal to the value of miny.
  1111.  
  1112. Return value
  1113.  
  1114.    none
  1115.  
  1116. Restrictions
  1117.  
  1118.    This routine has no effect in text video modes.
  1119.  
  1120. See also
  1121.  
  1122.    fg_clprectw, fg_rect, fg_rectw, fg_setclip
  1123.  
  1124. Examples
  1125.  
  1126.    10-1, 10-2, 10-3, 10-4
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.                                       15
  1147. fg_clprectw
  1148.  
  1149.  
  1150. Prototype
  1151.  
  1152.    void fg_clprectw (double xmin, double xmax, double ymin, double ymax);
  1153.  
  1154. Description
  1155.  
  1156.    The fg_clprectw routine draws a solid (filled) rectangle in world space,
  1157.    with respect to the clipping region.
  1158.  
  1159. Parameters
  1160.  
  1161.    xmin is the world space x coordinate of the rectangle's left edge.
  1162.  
  1163.    xmax is the world space x coordinate of the rectangle's right edge.  It
  1164.    must be greater than or equal to the value of xmin.
  1165.  
  1166.    ymin is the world space y coordinate of the rectangle's bottom edge.
  1167.  
  1168.    ymax is the world space y coordinate of the rectangle's top edge.  It must
  1169.    be greater than or equal to the value of ymin.
  1170.  
  1171. Return value
  1172.  
  1173.    none
  1174.  
  1175. Restrictions
  1176.  
  1177.    This routine is not available in Fastgraph/Light and has no effect in text
  1178.    video modes.
  1179.  
  1180. See also
  1181.  
  1182.    fg_clprect, fg_rect, fg_rectw, fg_setclip
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.                                       16
  1206. fg_cursor
  1207.  
  1208.  
  1209. Prototype
  1210.  
  1211.    void fg_cursor (int state);
  1212.  
  1213. Description
  1214.  
  1215.    The fg_cursor routine determines the ROM BIOS cursor visibility in text
  1216.    video modes.  After calling fg_setmode, the cursor is made visible by
  1217.    default.
  1218.  
  1219. Parameters
  1220.  
  1221.    The state parameter defines the cursor visibility.  If it is 0, the cursor
  1222.    becomes invisible; if it is 1, the cursor becomes visible.
  1223.  
  1224. Return value
  1225.  
  1226.    none
  1227.  
  1228. Restrictions
  1229.  
  1230.    This routine has no effect in graphics video modes.
  1231.  
  1232. Examples
  1233.  
  1234.    3-1, 3-2, 3-3, 3-4, 5-14, 7-1, 7-2, 7-3, 8-3, 8-5, 8-7, 9-7, 9-20, 9-21,
  1235.    9-23, 11-4
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.                                       17
  1265. fg_dash
  1266.  
  1267.  
  1268. Prototype
  1269.  
  1270.    void fg_dash (int ix, int iy, int pattern);
  1271.  
  1272. Description
  1273.  
  1274.    The fg_dash routine draws a dashed line from the graphics cursor position
  1275.    to an absolute screen space position.  It also makes the destination
  1276.    position the new graphics cursor position.
  1277.  
  1278. Parameters
  1279.  
  1280.    ix is the screen space x coordinate of the destination position.
  1281.  
  1282.    iy is the screen space y coordinate of the destination position.
  1283.  
  1284.    pattern is a 16-bit value representing a cyclic dash pattern.  Bits that
  1285.    are 1 will result in a pixel being drawn; bits that are 0 will result in a
  1286.    pixel being skipped.
  1287.  
  1288. Return value
  1289.  
  1290.    none
  1291.  
  1292. Restrictions
  1293.  
  1294.    This routine has no effect in text video modes.
  1295.  
  1296. See also
  1297.  
  1298.    fg_dashrel, fg_dashrw, fg_dashw, fg_move
  1299.  
  1300. Examples
  1301.  
  1302.    6-6
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.                                       18
  1324. fg_dashrel
  1325.  
  1326.  
  1327. Prototype
  1328.  
  1329.    void fg_dashrel (int ix, int iy, int pattern);
  1330.  
  1331. Description
  1332.  
  1333.    The fg_dash routine draws a dashed line from the graphics cursor position
  1334.    to a screen space position relative to it.  It also makes the destination
  1335.    position the new graphics cursor position.
  1336.  
  1337. Parameters
  1338.  
  1339.    ix is the screen space x offset of the destination position.
  1340.  
  1341.    iy is the screen space y offset of the destination position.
  1342.  
  1343.    pattern is a 16-bit value representing a cyclic dash pattern.  Bits that
  1344.    are 1 will result in a pixel being drawn; bits that are 0 will result in a
  1345.    pixel being skipped.
  1346.  
  1347. Return value
  1348.  
  1349.    none
  1350.  
  1351. Restrictions
  1352.  
  1353.    This routine has no effect in text video modes.
  1354.  
  1355. See also
  1356.  
  1357.    fg_dash, fg_dashrw, fg_dashw, fg_moverel
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                                       19
  1383. fg_dashrw
  1384.  
  1385.  
  1386. Prototype
  1387.  
  1388.    void fg_dashrw (double x, double y, int pattern);
  1389.  
  1390. Description
  1391.  
  1392.    The fg_dashrw routine draws a dashed line from the graphics cursor position
  1393.    to a world space position relative to it.  It also makes the destination
  1394.    position the new graphics cursor position.
  1395.  
  1396. Parameters
  1397.  
  1398.    x is the world space x offset of the destination position.
  1399.  
  1400.    y is the world space y offset of the destination position.
  1401.  
  1402.    pattern is a 16-bit value representing a cyclic dash pattern.  Bits that
  1403.    are 1 will result in a pixel being drawn; bits that are 0 will result in a
  1404.    pixel being skipped.
  1405.  
  1406. Return value
  1407.  
  1408.    none
  1409.  
  1410. Restrictions
  1411.  
  1412.    This routine is not available in Fastgraph/Light and has no effect in text
  1413.    video modes.
  1414.  
  1415. See also
  1416.  
  1417.    fg_dash, fg_dashrel, fg_dashw, fg_moverw
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.                                       20
  1442. fg_dashw
  1443.  
  1444.  
  1445. Prototype
  1446.  
  1447.    void fg_dashw (double x, double y, int pattern);
  1448.  
  1449. Description
  1450.  
  1451.    The fg_dashw routine draws a dashed line from the graphics cursor position
  1452.    to an absolute world space position.  It also makes the destination
  1453.    position the new graphics cursor position.
  1454.  
  1455. Parameters
  1456.  
  1457.    x is the world space x coordinate of the destination position.
  1458.  
  1459.    y is the world space y coordinate of the destination position.
  1460.  
  1461.    pattern is a 16-bit value representing a cyclic dash pattern.  Bits that
  1462.    are 1 will result in a pixel being drawn; bits that are 0 will result in a
  1463.    pixel being skipped.
  1464.  
  1465. Return value
  1466.  
  1467.    none
  1468.  
  1469. Restrictions
  1470.  
  1471.    This routine is not available in Fastgraph/Light and has no effect in text
  1472.    video modes.
  1473.  
  1474. See also
  1475.  
  1476.    fg_dash, fg_dashrel, fg_dashrw, fg_movew
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.                                       21
  1501. fg_defcolor
  1502.  
  1503.  
  1504. Prototype
  1505.  
  1506.    void fg_defcolor (int index, int value);
  1507.  
  1508. Description
  1509.  
  1510.    The fg_defcolor routine assigns a color value to a virtual color index.
  1511.  
  1512. Parameters
  1513.  
  1514.    index is the virtual color index to define, between 0 and 255.
  1515.  
  1516.    value is the color value to assign to the specified color index.  It must
  1517.    be between 0 and the maximum color value for the current video mode.
  1518.  
  1519. Return value
  1520.  
  1521.    none
  1522.  
  1523. Restrictions
  1524.  
  1525.    This routine has no effect in text video modes or in 256-color graphics
  1526.    video modes.
  1527.  
  1528. See also
  1529.  
  1530.    fg_getindex, fg_palette, fg_setcolor
  1531.  
  1532. Examples
  1533.  
  1534.    5-13, 5-14
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.                                       22
  1560. fg_dispfile
  1561.  
  1562.  
  1563. Prototype
  1564.  
  1565.    void fg_dispfile (char *filename, int width, int format);
  1566.  
  1567. Description
  1568.  
  1569.    The fg_dispfile routine displays an image stored in Fastgraph's standard or
  1570.    packed pixel run format, where the image resides in an external file.  The
  1571.    image will be positioned so that its lower left corner is at the graphics
  1572.    cursor position.  Refer to the descriptions of the fg_display and
  1573.    fg_displayp routines for more information about the two pixel run formats.
  1574.  
  1575. Parameters
  1576.  
  1577.    filename is the name of the file that contains the image.  A device and
  1578.    path name may be included as part of the file name.  The file name must be
  1579.    terminated by a null character (that is, a zero byte).
  1580.  
  1581.    width is the width of the image in pixels.  It must be greater than zero.
  1582.  
  1583.    format specifies the image format.  The value of format must be 0 if the
  1584.    image is in standard pixel run format, and 1 if the image is in packed
  1585.    pixel run format.
  1586.  
  1587. Return value
  1588.  
  1589.    none
  1590.  
  1591. Restrictions
  1592.  
  1593.    This routine has no effect in text video modes.
  1594.  
  1595. See also
  1596.  
  1597.    fg_display, fg_displayp, fg_pattern
  1598.  
  1599. Examples
  1600.  
  1601.    9-13, 9-14
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.                                       23
  1619. fg_display
  1620.  
  1621.  
  1622. Prototype
  1623.  
  1624.    void fg_display (char *map_array, int runs, int width);
  1625.  
  1626. Description
  1627.  
  1628.    The fg_display routine displays an image stored in Fastgraph's standard
  1629.    pixel run format, where the image resides in an array.  The image will be
  1630.    positioned so that its lower left corner is at the graphics cursor
  1631.    position.
  1632.  
  1633. Parameters
  1634.  
  1635.    map_array is the arbitrary-length array containing the pixel run map.  The
  1636.    pixel runs are represented by (color,count) pairs, as shown below.
  1637.  
  1638.  
  1639.                              [0]   color for run 1
  1640.  
  1641.                              [1]   count for run 1
  1642.  
  1643.                              [2]   color for run 2
  1644.  
  1645.                              [3]   count for run 2
  1646.                               .
  1647.                               .
  1648.                               .
  1649.  
  1650.                           [2n-2]   color for run n
  1651.  
  1652.                           [2n-1]   count for run n
  1653.  
  1654.  
  1655.    Each "color" element is a value between 0 and 255 specifying the color
  1656.    index for that pixel run.  Each "count" element is a value between 0 and
  1657.    255 specifying the length in pixels of that pixel run.
  1658.  
  1659.    runs is the number of pixel runs to display from the pixel run map.  It is
  1660.    normally 1/2 the size of the map_array array.
  1661.  
  1662.    width is the width of the image in pixels.  It must be greater than zero.
  1663.  
  1664. Return value
  1665.  
  1666.    none
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.                                       24
  1678. fg_display (continued)
  1679.  
  1680.  
  1681. Restrictions
  1682.  
  1683.    This routine has no effect in text video modes.
  1684.  
  1685. See also
  1686.  
  1687.    fg_dispfile, fg_displayp, fg_pattern
  1688.  
  1689. Examples
  1690.  
  1691.    9-10, 9-12
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.                                       25
  1737. fg_displayp
  1738.  
  1739.  
  1740. Prototype
  1741.  
  1742.    void fg_displayp (char *map_array, int runs, int width);
  1743.  
  1744. Description
  1745.  
  1746.    The fg_displayp routine displays an image stored in Fastgraph's packed
  1747.    pixel run format, where the image resides in an array.  The image will be
  1748.    positioned so that its lower left corner is at the graphics cursor
  1749.    position.
  1750.  
  1751. Parameters
  1752.  
  1753.    map_array is the arbitrary-length array containing the pixel run map.  The
  1754.    pixel runs are represented by (color,count) pairs, as shown below.
  1755.  
  1756.                         7                4   3                0
  1757.  
  1758.                    [0]    color for run 1     color for run 2
  1759.  
  1760.                    [1]              count for run 1
  1761.  
  1762.                    [2]              count for run 2
  1763.  
  1764.                    [3]    color for run 3     color for run 4
  1765.  
  1766.                    [4]              count for run 3
  1767.  
  1768.                    [5]              count for run 4
  1769.                     .
  1770.                     .
  1771.                     .
  1772.  
  1773.               [3n/2-3]   color for run n-1    color for run n
  1774.  
  1775.               [3n/2-2]             count for run n-1
  1776.  
  1777.               [3n/2-1]              count for run n
  1778.  
  1779.  
  1780.    Each "color" element is a value between 0 and 15 specifying the color index
  1781.    for that pixel run.  Each "count" element is a value between 0 and 255
  1782.    specifying the length in pixels of that pixel run.
  1783.  
  1784.    runs is the number of pixel runs to display from the pixel run map.  It is
  1785.    normally 2/3 the size of the map_array array.
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.                                       26
  1796. fg_displayp (continued)
  1797.  
  1798.  
  1799.    width is the width of the image in pixels.  It must be greater than zero.
  1800.  
  1801. Return value
  1802.  
  1803.    none
  1804.  
  1805. Restrictions
  1806.  
  1807.    This routine has no effect in text video modes.
  1808.  
  1809. See also
  1810.  
  1811.    fg_dispfile, fg_display, fg_pattern
  1812.  
  1813. Examples
  1814.  
  1815.    9-11, 9-12
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.                                       27
  1855. fg_draw
  1856.  
  1857.  
  1858. Prototype
  1859.  
  1860.    void fg_draw (int ix, int iy);
  1861.  
  1862. Description
  1863.  
  1864.    The fg_draw routine draws a solid line from the graphics cursor position to
  1865.    an absolute screen space position.  It also makes the destination position
  1866.    the new graphics cursor position.
  1867.  
  1868. Parameters
  1869.  
  1870.    ix is the screen space x coordinate of the destination position.
  1871.  
  1872.    iy is the screen space y coordinate of the destination position.
  1873.  
  1874. Return value
  1875.  
  1876.    none
  1877.  
  1878. Restrictions
  1879.  
  1880.    This routine has no effect in text video modes.
  1881.  
  1882. See also
  1883.  
  1884.    fg_drawrel, fg_drawrw, fg_draww, fg_move
  1885.  
  1886. Examples
  1887.  
  1888.    6-2, 6-5, 11-5, 11-6
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.                                       28
  1914. fg_drawmap
  1915.  
  1916.  
  1917. Prototype
  1918.  
  1919.    void fg_drawmap (char *map_array, int width, int height);
  1920.  
  1921. Description
  1922.  
  1923.    The fg_drawmap routine displays an image stored as a mode-independent bit
  1924.    map.  The image will be positioned so that its lower left corner is at the
  1925.    graphics cursor position.  Refer to the Fastgraph User's Guide for complete
  1926.    information about mode-independent bit maps.
  1927.  
  1928. Parameters
  1929.  
  1930.    map_array is the arbitrary-length array containing the bit map.  Each byte
  1931.    of map_array represents eight pixels.  Bits that are set (1) result in the
  1932.    corresponding pixel being displayed in the current color.  Bits that are
  1933.    reset (0) leave the corresponding pixel unchanged.
  1934.  
  1935.    width is the width in bytes of the bit map.
  1936.  
  1937.    height is the height in bytes (pixel rows) of the bit map.
  1938.  
  1939. Return value
  1940.  
  1941.    none
  1942.  
  1943. Restrictions
  1944.  
  1945.    none
  1946.  
  1947. See also
  1948.  
  1949.    fg_drwimage, fg_getmap
  1950.  
  1951. Examples
  1952.  
  1953.    9-1, 9-2, 9-17, 9-18
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.                                       29
  1973. fg_drawmask
  1974.  
  1975.  
  1976. Prototype
  1977.  
  1978.    void fg_drawmask (char *map_array, int runs, int width);
  1979.  
  1980. Description
  1981.  
  1982.    The fg_drawmask routine displays an image stored as a masking map.  The
  1983.    image will be positioned so that its lower left corner is at the graphics
  1984.    cursor position.  Refer to the Fastgraph User's Guide for a complete
  1985.    discussion of masking maps.
  1986.  
  1987. Parameters
  1988.  
  1989.    map_array is the arbitrary-length array containing the masking map.  The
  1990.    masking map is a series of alternating "protect" and "zero" pixel runs, as
  1991.    shown below.
  1992.  
  1993.  
  1994.                       [1]   length of 1st protect run
  1995.  
  1996.                       [2]   length of 1st  zero   run
  1997.  
  1998.                       [3]   length of 2nd protect run
  1999.  
  2000.                       [4]   length of 2nd  zero   run
  2001.                        .
  2002.                        .
  2003.                        .
  2004.  
  2005.                     [n-2]   length of final protect run
  2006.  
  2007.                     [n-1]   length of final  zero   run
  2008.  
  2009.  
  2010.    The "protect" runs protect video memory, while the "zero" runs zero video
  2011.    memory (that is, set the pixels to the background color).  The length of
  2012.    each run must be between 0 and 255.
  2013.  
  2014.    runs is the number of pixel runs in the masking map.
  2015.  
  2016.    width is the width in pixels of the masking map.
  2017.  
  2018. Return value
  2019.  
  2020.    none
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.                                       30
  2032. fg_drawmask (continued)
  2033.  
  2034.  
  2035. Restrictions
  2036.  
  2037.    This routine has no effect in text video modes, or in the native EGA and
  2038.    VGA graphics video modes.
  2039.  
  2040. See also
  2041.  
  2042.    fg_clipmask, fg_flipmask, fg_revmask
  2043.  
  2044. Examples
  2045.  
  2046.    9-15, 9-16
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.                                       31
  2091. fg_drawrel
  2092.  
  2093.  
  2094. Prototype
  2095.  
  2096.    void fg_drawrel (int ix, int iy);
  2097.  
  2098. Description
  2099.  
  2100.    The fg_drawrel routine draws a solid line from the graphics cursor position
  2101.    to a screen space position relative to it.  It also makes the destination
  2102.    position the new graphics cursor position.
  2103.  
  2104. Parameters
  2105.  
  2106.    ix is the screen space x offset of the destination position.
  2107.  
  2108.    iy is the screen space y offset of the destination position.
  2109.  
  2110. Return value
  2111.  
  2112.    none
  2113.  
  2114. Restrictions
  2115.  
  2116.    This routine has no effect in text video modes.
  2117.  
  2118. See also
  2119.  
  2120.    fg_draw, fg_drawrw, fg_draww, fg_moverel
  2121.  
  2122. Examples
  2123.  
  2124.    6-3, 6-14
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.                                       32
  2150. fg_drawrw
  2151.  
  2152.  
  2153. Prototype
  2154.  
  2155.    void fg_drawrw (double x, double y);
  2156.  
  2157. Description
  2158.  
  2159.    The fg_drawrw routine draws a solid line from the graphics cursor position
  2160.    to a world space position relative to it.  It also makes the destination
  2161.    position the new graphics cursor position.
  2162.  
  2163. Parameters
  2164.  
  2165.    x is the world space x offset of the destination position.
  2166.  
  2167.    y is the world space y offset of the destination position.
  2168.  
  2169. Return value
  2170.  
  2171.    none
  2172.  
  2173. Restrictions
  2174.  
  2175.    This routine is not available in Fastgraph/Light and has no effect in text
  2176.    video modes.
  2177.  
  2178. See also
  2179.  
  2180.    fg_draw, fg_drawrel, fg_draww, fg_moverw
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.  
  2208.                                       33
  2209. fg_draww
  2210.  
  2211.  
  2212. Prototype
  2213.  
  2214.    void fg_draww (double x, double y);
  2215.  
  2216. Description
  2217.  
  2218.    The fg_draww routine draws a dashed line from the graphics cursor position
  2219.    to an absolute world space position.  It also makes the destination
  2220.    position the new graphics cursor position.
  2221.  
  2222. Parameters
  2223.  
  2224.    x is the world space x coordinate of the destination position.
  2225.  
  2226.    y is the world space y coordinate of the destination position.
  2227.  
  2228. Return value
  2229.  
  2230.    none
  2231.  
  2232. Restrictions
  2233.  
  2234.    This routine is not available in Fastgraph/Light and has no effect in text
  2235.    video modes.
  2236.  
  2237. See also
  2238.  
  2239.    fg_draw, fg_drawrel, fg_drawrw, fg_movew
  2240.  
  2241. Examples
  2242.  
  2243.    6-4
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.                                       34
  2268. fg_drect
  2269.  
  2270.  
  2271. Prototype
  2272.  
  2273.    void fg_drect (int minx, int maxx, int miny, int maxy, char *matrix);
  2274.  
  2275. Description
  2276.  
  2277.    The fg_drect routine draws a dithered rectangle in screen space, without
  2278.    regard to the clipping region.
  2279.  
  2280. Parameters
  2281.  
  2282.    minx is the screen space x coordinate of the rectangle's left edge.
  2283.  
  2284.    maxx is the screen space x coordinate of the rectangle's right edge.  It
  2285.    must be greater than or equal to the value of minx.
  2286.  
  2287.    miny is the screen space y coordinate of the rectangle's top edge.
  2288.  
  2289.    maxy is the screen space y coordinate of the rectangle's bottom edge.  It
  2290.    must be greater than or equal to the value of miny.
  2291.  
  2292.    matrix is a four-element array (an eight-element array in 256-color
  2293.    graphics modes) that defines the dithering matrix.  The format of the
  2294.    dithering matrix is dependent on the video mode; refer to the Fastgraph
  2295.    User's Guide for more information.
  2296.  
  2297. Return value
  2298.  
  2299.    none
  2300.  
  2301. Restrictions
  2302.  
  2303.    This routine has no effect in text video modes.
  2304.  
  2305. See also
  2306.  
  2307.    fg_drectw, fg_rect, fg_rectw
  2308.  
  2309.  
  2310. Examples
  2311.  
  2312.    6-11, 6-12, 6-13
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.                                       35
  2327. fg_drectw
  2328.  
  2329.  
  2330. Prototype
  2331.  
  2332.    void fg_drectw (double xmin, double xmax, double ymin, double ymax, char
  2333.    *matrix);
  2334.  
  2335. Description
  2336.  
  2337.    The fg_drectw routine draws a dithered rectangle in world space, without
  2338.    regard to the clipping region.
  2339.  
  2340. Parameters
  2341.  
  2342.    xmin is the world space x coordinate of the rectangle's left edge.
  2343.  
  2344.    xmax is the world space x coordinate of the rectangle's right edge.  It
  2345.    must be greater than or equal to the value of xmin.
  2346.  
  2347.    ymin is the world space y coordinate of the rectangle's bottom edge.
  2348.  
  2349.    ymax is the world space y coordinate of the rectangle's top edge.  It must
  2350.    be greater than or equal to the value of ymin.
  2351.  
  2352.    matrix is a four-element array (an eight-element array in 256-color
  2353.    graphics modes) that defines the dithering matrix.  The format of the
  2354.    dithering matrix is dependent on the video mode; refer to the Fastgraph
  2355.    User's Guide for more information.
  2356.  
  2357. Return value
  2358.  
  2359.    none
  2360.  
  2361. Restrictions
  2362.  
  2363.    This routine is not available in Fastgraph/Light and has no effect in text
  2364.    video modes.
  2365.  
  2366. See also
  2367.  
  2368.    fg_drect, fg_rect, fg_rectw
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.                                       36
  2386. fg_drwimage
  2387.  
  2388.  
  2389. Prototype
  2390.  
  2391.    void fg_drwimage (char *map_array, int width, int height);
  2392.  
  2393. Description
  2394.  
  2395.    The fg_drwimage routine displays an image stored as a mode-specific bit
  2396.    map.  The image will be positioned so that its lower left corner is at the
  2397.    graphics cursor position (or the text cursor position in text video modes).
  2398.    Refer to the Fastgraph User's Guide for complete information about mode-
  2399.    specific bit maps.
  2400.  
  2401. Parameters
  2402.  
  2403.    map_array is the arbitrary-length array containing the bit map.  For EGA
  2404.    and VGA graphics modes, each color must be in a separate bit map.  For all
  2405.    other video modes, all colors are in a single bit map.
  2406.  
  2407.    width is the width in bytes of the bit map.
  2408.  
  2409.    height is the height in bytes (pixel rows) of the bit map.
  2410.  
  2411. Return value
  2412.  
  2413.    none
  2414.  
  2415. Restrictions
  2416.  
  2417.    none
  2418.  
  2419. See also
  2420.  
  2421.    fg_clpimage, fg_flpimage, fg_getimage, fg_revimage
  2422.  
  2423. Examples
  2424.  
  2425.    9-3, 9-4, 9-5, 9-6, 9-7, 9-8, 9-9, 9-16, 9-19, 9-20
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.                                       37
  2445. fg_egacheck
  2446.  
  2447.  
  2448. Prototype
  2449.  
  2450.    int fg_egacheck (void);
  2451.  
  2452. Description
  2453.  
  2454.    The fg_egacheck routine returns information about the active EGA adapter
  2455.    and display (or the EGA emulation capabilities of a VGA).  It is useful in
  2456.    checking if the adapter has enough memory to run a program.
  2457.  
  2458. Parameters
  2459.  
  2460.    none
  2461.  
  2462. Return value
  2463.  
  2464.    The fg_egacheck routine returns a value of 0 if an EGA is not found, or if
  2465.    an EGA without an Enhanced Color Display (ECD) is detected.  Otherwise,
  2466.    fg_egacheck returns a positive integer indicating the number of 64K-byte
  2467.    increments of video memory on the EGA, as summarized below.
  2468.  
  2469.      1 = EGA with 64K video memory
  2470.      2 = EGA with 128K video memory
  2471.      3 = EGA with 192K video memory
  2472.      4 = EGA with 256K video memory
  2473.  
  2474. Restrictions
  2475.  
  2476.    none
  2477.  
  2478. Examples
  2479.  
  2480.    3-5, 15-2
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.                                       38
  2504. fg_ellipse
  2505.  
  2506.  
  2507. Prototype
  2508.  
  2509.    void fg_ellipse (int horiz, int vert);
  2510.  
  2511. Description
  2512.  
  2513.    The fg_ellipse routine draws an unfilled ellipse in screen space.  The
  2514.    ellipse is centered at the current graphics cursor position, and its size
  2515.    is determined by the specified lengths of its semi-axes.
  2516.  
  2517. Parameters
  2518.  
  2519.    horiz defines the horizontal semi-axis of the ellipse (the absolute screen
  2520.    space distance from the center of the ellipse to its horizontal extremity).
  2521.  
  2522.    vert defines the vertical semi-axis of the ellipse (the absolute screen
  2523.    space distance from the center of the ellipse to its vertical extremity).
  2524.  
  2525. Return value
  2526.  
  2527.    none
  2528.  
  2529. Restrictions
  2530.  
  2531.    This routine has no effect in text video modes.
  2532.  
  2533. See also
  2534.  
  2535.    fg_circle, fg_circlew, fg_ellipsew
  2536.  
  2537. Examples
  2538.  
  2539.    6-9, 10-4, 10-5
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.                                       39
  2563. fg_ellipsew
  2564.  
  2565.  
  2566. Prototype
  2567.  
  2568.    void fg_ellipsew (double horiz, double vert);
  2569.  
  2570. Description
  2571.  
  2572.    The fg_ellipsew routine draws an unfilled ellipse in world space.  The
  2573.    ellipse is centered at the current graphics cursor position, and its size
  2574.    is determined by the specified lengths of its semi-axes.
  2575.  
  2576. Parameters
  2577.  
  2578.    horiz defines the horizontal semi-axis of the ellipse (the absolute world
  2579.    space distance from the center of the ellipse to its horizontal extremity).
  2580.  
  2581.    vert defines the vertical semi-axis of the ellipse (the absolute world
  2582.    space distance from the center of the ellipse to its vertical extremity).
  2583.  
  2584. Return value
  2585.  
  2586.    none
  2587.  
  2588. Restrictions
  2589.  
  2590.    This routine is not available in Fastgraph/Light and has no effect in text
  2591.    video modes.
  2592.  
  2593. See also
  2594.  
  2595.    fg_circle, fg_circlew, fg_ellipse
  2596.  
  2597. Examples
  2598.  
  2599.    6-8
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.                                       40
  2622. fg_erase
  2623.  
  2624.  
  2625. Prototype
  2626.  
  2627.    void fg_erase (void);
  2628.  
  2629. Description
  2630.  
  2631.    The fg_erase routine clears the active video page.  In text modes, fg_erase
  2632.    stores a space character (ASCII 32) with a gray foreground attribute in
  2633.    each character cell.  In graphics modes, fg_erase sets each pixel to zero.
  2634.  
  2635. Parameters
  2636.  
  2637.    none
  2638.  
  2639. Return value
  2640.  
  2641.    none
  2642.  
  2643. Restrictions
  2644.  
  2645.    none
  2646.  
  2647. See also
  2648.  
  2649.    fg_reset
  2650.  
  2651. Examples
  2652.  
  2653.    9-12, 9-13
  2654.  
  2655.  
  2656.  
  2657.  
  2658.  
  2659.  
  2660.  
  2661.  
  2662.  
  2663.  
  2664.  
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.                                       41
  2681. fg_fadein
  2682.  
  2683.  
  2684. Prototype
  2685.  
  2686.    void fg_fadein (int delay);
  2687.  
  2688. Description
  2689.  
  2690.    The fg_fadein routine replaces the visual page contents with the hidden
  2691.    page contents.  The replacement is done randomly in small sections, thus
  2692.    giving a "fade in" effect.
  2693.  
  2694. Parameters
  2695.  
  2696.    delay controls the speed at which the replacement takes place.  A value of
  2697.    zero means to perform the replacement as quickly as possible, while 1 is
  2698.    slightly slower, 2 is slower yet, and so forth.
  2699.  
  2700. Return value
  2701.  
  2702.    none
  2703.  
  2704. Restrictions
  2705.  
  2706.    This routine has no effect in text video modes.
  2707.  
  2708. See also
  2709.  
  2710.    fg_fadeout, fg_sethpage
  2711.  
  2712. Examples
  2713.  
  2714.    11-2
  2715.  
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.                                       42
  2740. fg_fadeout
  2741.  
  2742.  
  2743. Prototype
  2744.  
  2745.    void fg_fadeout (int delay);
  2746.  
  2747. Description
  2748.  
  2749.    The fg_fadeout routine replaces the visual page contents with pixels of the
  2750.    current color.  The replacement is done randomly in small sections, thus
  2751.    giving a "fade out" effect.
  2752.  
  2753. Parameters
  2754.  
  2755.    delay controls the speed at which the replacement takes place.  A value of
  2756.    zero means to perform the replacement as quickly as possible, while 1 is
  2757.    slightly slower, 2 is slower yet, and so forth.
  2758.  
  2759. Return value
  2760.  
  2761.    none
  2762.  
  2763. Restrictions
  2764.  
  2765.    This routine has no effect in text video modes.
  2766.  
  2767. See also
  2768.  
  2769.    fg_fadein, fg_setcolor
  2770.  
  2771. Examples
  2772.  
  2773.    11-1
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.                                       43
  2799. fg_flipmask
  2800.  
  2801.  
  2802. Prototype
  2803.  
  2804.    void fg_flipmask (char *map_array, int runs, int width);
  2805.  
  2806. Description
  2807.  
  2808.    The fg_flipmask routine displays a reversed clipped image stored as a
  2809.    masking map.  The image will be positioned so that its lower left corner is
  2810.    at the graphics cursor position.  Refer to the description of the
  2811.    fg_drawmask routine for more information about masking maps.
  2812.  
  2813. Parameters
  2814.  
  2815.    map_array is the arbitrary-length array containing the masking map.
  2816.  
  2817.    runs is the number of pixel runs in the masking map.
  2818.  
  2819.    width is the width in pixels of the masking map.
  2820.  
  2821. Return value
  2822.  
  2823.    none
  2824.  
  2825. Restrictions
  2826.  
  2827.    This routine has no effect in text video modes, or in the native EGA and
  2828.    VGA graphics video modes.
  2829.  
  2830. See also
  2831.  
  2832.    fg_clipmask, fg_drawmask, fg_revmask, fg_setclip
  2833.  
  2834. Examples
  2835.  
  2836.    9-15
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.  
  2850.  
  2851.  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.  
  2857.                                       44
  2858. fg_flpimage
  2859.  
  2860.  
  2861. Prototype
  2862.  
  2863.    void fg_flpimage (char *map_array, int width, int height);
  2864.  
  2865. Description
  2866.  
  2867.    The fg_flpimage routine displays a reversed clipped image stored as a mode-
  2868.    specific bit map.  The image will be positioned so that its lower left
  2869.    corner is at the graphics cursor position.  Only that part of the image
  2870.    that falls within the current clipping limits will be displayed, but the
  2871.    clipping limits will be extended to a byte boundary if necessary.  Refer to
  2872.    the Fastgraph User's Guide for complete information about mode-specific bit
  2873.    maps.
  2874.  
  2875. Parameters
  2876.  
  2877.    map_array is the arbitrary-length array containing the bit map.  For EGA
  2878.    and VGA graphics modes, each color must be in a separate bit map.  For all
  2879.    other graphics modes, all colors are in a single bit map.
  2880.  
  2881.    width is the width in bytes of the bit map.
  2882.  
  2883.    height is the height in bytes (pixel rows) of the bit map.
  2884.  
  2885. Return value
  2886.  
  2887.    none
  2888.  
  2889. Restrictions
  2890.  
  2891.    This routine has no effect in text video modes.
  2892.  
  2893. See also
  2894.  
  2895.    fg_clpimage, fg_drwimage, fg_getimage, fg_revimage, fg_setclip
  2896.  
  2897. Examples
  2898.  
  2899.    9-8, 9-9
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.                                       45
  2917. fg_freepage
  2918.  
  2919.  
  2920. Prototype
  2921.  
  2922.    int fg_freepage (int page_number);
  2923.  
  2924. Description
  2925.  
  2926.    The fg_freepage routine releases a virtual video page created with the
  2927.    fg_allocate routine.
  2928.  
  2929. Parameters
  2930.  
  2931.    page_number is the number by which the virtual page will be referenced.  It
  2932.    must be between 0 and 15.
  2933.  
  2934. Return value
  2935.  
  2936.    A status code indicating the success or failure of the virtual page
  2937.    creation, as shown below.
  2938.  
  2939.      0 = virtual page created
  2940.      7 = virtual page created, but memory control blocks were destroyed
  2941.      9 = attempt to use fg_freepage on a virtual page that was never created
  2942.  
  2943. Restrictions
  2944.  
  2945.    This routine has no effect if page_number references a physical video page,
  2946.    or a virtual page that was never created.
  2947.  
  2948. See also
  2949.  
  2950.    fg_allocate
  2951.  
  2952. Examples
  2953.  
  2954.    8-3, 8-4, 8-5, 8-6, 8-8, 9-21, 9-22, 9-23, 10-4, 10-5, 11-2, 11-5, 15-1
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.                                       46
  2976. fg_getaddr
  2977.  
  2978.  
  2979. Prototype
  2980.  
  2981.    int fg_getaddr (void);
  2982.  
  2983. Description
  2984.  
  2985.    The fg_getaddr routine returns the segment address of the active video
  2986.    page.
  2987.  
  2988. Parameters
  2989.  
  2990.    none
  2991.  
  2992. Return value
  2993.  
  2994.    The segment address of the active video page.
  2995.  
  2996. Restrictions
  2997.  
  2998.    none
  2999.  
  3000. See also
  3001.  
  3002.    fg_setpage
  3003.  
  3004. Examples
  3005.  
  3006.    8-8
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.                                       47
  3035. fg_getclock
  3036.  
  3037.  
  3038. Prototype
  3039.  
  3040.    long fg_getclock (void);
  3041.  
  3042. Description
  3043.  
  3044.    The fg_getclock routine returns the number of clock ticks since midnight.
  3045.  
  3046. Parameters
  3047.  
  3048.    none
  3049.  
  3050. Return value
  3051.  
  3052.    The number of clock ticks since midnight.  There are approximately 18.2
  3053.    clock ticks per second.
  3054.  
  3055. Restrictions
  3056.  
  3057.    none
  3058.  
  3059. Examples
  3060.  
  3061.    14-2
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.                                       48
  3094. fg_getcolor
  3095.  
  3096.  
  3097. Prototype
  3098.  
  3099.    int fg_getcolor (void);
  3100.  
  3101. Description
  3102.  
  3103.    The fg_getcolor routine returns the current text attribute (in text modes)
  3104.    or color index (in graphics modes), as defined by the most recent call to
  3105.    fg_setattr or fg_setcolor.
  3106.  
  3107. Parameters
  3108.  
  3109.    none
  3110.  
  3111. Return value
  3112.  
  3113.    In graphics video modes, the return value is the current color index.  In
  3114.    text modes, it is the current text attribute.
  3115.  
  3116. Restrictions
  3117.  
  3118.    none
  3119.  
  3120. See also
  3121.  
  3122.    fg_setattr, fg_setcolor
  3123.  
  3124.  
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.  
  3137.  
  3138.  
  3139.  
  3140.  
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.                                       49
  3153. fg_gethpage
  3154.  
  3155.  
  3156. Prototype
  3157.  
  3158.    int fg_gethpage (void);
  3159.  
  3160. Description
  3161.  
  3162.    The fg_gethpage routine returns the hidden video page number (as set in the
  3163.    most recent call to fg_sethpage).
  3164.  
  3165. Parameters
  3166.  
  3167.    none
  3168.  
  3169. Return value
  3170.  
  3171.    The number of the hidden video page, between 0 and 15.
  3172.  
  3173. Restrictions
  3174.  
  3175.    none
  3176.  
  3177. See also
  3178.  
  3179.    fg_sethpage
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.                                       50
  3212. fg_getimage
  3213.  
  3214.  
  3215. Prototype
  3216.  
  3217.    void fg_getimage (char *map_array, int width, int height);
  3218.  
  3219. Description
  3220.  
  3221.    The fg_getimage routine retrieves an image as a mode-specific bit map.  The
  3222.    graphics cursor position (the text cursor position in text video modes)
  3223.    defines the lower left corner of the image to retrieve. Refer to the
  3224.    Fastgraph User's Guide for complete information about mode-specific bit
  3225.    maps.
  3226.  
  3227. Parameters
  3228.  
  3229.    map_array is the arbitrary-length array in which to retrieve the bit map.
  3230.    For EGA and VGA graphics modes, only pixels of the current color are
  3231.    retrieved.  For all other video modes, the entire image is retrieved, with
  3232.    all colors combined into a single bit map.  In QuickBASIC, you must
  3233.    explicitly declare map_array as a fixed-length string variable of length
  3234.    width*height.
  3235.  
  3236.    width is the width in bytes of the bit map.
  3237.  
  3238.    height is the height in bytes (pixel rows) of the bit map.
  3239.  
  3240. Return value
  3241.  
  3242.    none
  3243.  
  3244. Restrictions
  3245.  
  3246.    none
  3247.  
  3248. See also
  3249.  
  3250.    fg_clpimage, fg_drwimage, fg_flpimage, fg_getmap, fg_revimage
  3251.  
  3252. Examples
  3253.  
  3254.    9-19, 9-20
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.                                       51
  3271. fg_getindex
  3272.  
  3273.  
  3274. Prototype
  3275.  
  3276.    int fg_getindex (int index);
  3277.  
  3278. Description
  3279.  
  3280.    The fg_getindex routine returns the color value assigned to a specified
  3281.    virtual color index.
  3282.  
  3283. Parameters
  3284.  
  3285.    index is the virtual color index to retrieve, between 0 and 255.
  3286.  
  3287. Return value
  3288.  
  3289.    In graphics video modes with fewer than 256 available colors, the return
  3290.    value is the color value assigned to the specified virtual index.  In text
  3291.    modes and 256-color graphics modes, the fg_getindex routine returns the
  3292.    value passed to it.
  3293.  
  3294. Restrictions
  3295.  
  3296.    none
  3297.  
  3298. See also
  3299.  
  3300.    fg_defcolor, fg_palette, fg_setcolor
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  
  3313.  
  3314.  
  3315.  
  3316.  
  3317.  
  3318.  
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.  
  3325.  
  3326.  
  3327.  
  3328.  
  3329.                                       52
  3330. fg_getkey
  3331.  
  3332.  
  3333. Prototype
  3334.  
  3335.    void fg_getkey (unsigned char *key, unsigned char *aux);
  3336.  
  3337. Description
  3338.  
  3339.    The fg_getkey routine waits for a keystroke, or reads the next entry from
  3340.    the BIOS keyboard buffer (without echo).  It returns the keystroke's
  3341.    standard or extended keyboard code (a list of these appears in chapter 12
  3342.    of the Fastgraph User's Guide).
  3343.  
  3344. Parameters
  3345.  
  3346.    key receives the keystroke's standard keyboard code if it represents a
  3347.    standard character.  If the keystroke represents an extended character, key
  3348.    will be set to zero.  In QuickBASIC, you must explicitly declare key as a
  3349.    fixed-length string variable of length 1.
  3350.  
  3351.    aux receives the keystroke's extended keyboard code if it represents an
  3352.    extended character.  If the keystroke represents a standard character, aux
  3353.    will be set to zero.  In QuickBASIC, you must explicitly declare aux as a
  3354.    fixed-length string variable of length 1.
  3355.  
  3356. Return value
  3357.  
  3358.    none
  3359.  
  3360. Restrictions
  3361.  
  3362.    none
  3363.  
  3364. See also
  3365.  
  3366.    fg_intkey, fg_waitkey
  3367.  
  3368. Examples
  3369.  
  3370.    12-1, 14-2
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.                                       53
  3389. fg_getmap
  3390.  
  3391.  
  3392. Prototype
  3393.  
  3394.    void fg_getmap (char *map_array, int width, int height);
  3395.  
  3396. Description
  3397.  
  3398.    The fg_getmap routine retrieves an image as a mode-independent bit map.
  3399.    The graphics cursor position defines the lower left corner of the image to
  3400.    retrieve.  Refer to the Fastgraph User's Guide for complete information
  3401.    about mode-independent bit maps.
  3402.  
  3403. Parameters
  3404.  
  3405.    map_array is the arbitrary-length array in which to retrieve the bit map.
  3406.    Each byte of map_array represents eight pixels.  Pixels of the current
  3407.    color set the corresponding bits in map_array.  Pixels of other colors make
  3408.    the corresponding map_array bits zero.  In QuickBASIC, you must explicitly
  3409.    declare map_array as a fixed-length string variable of length width*height.
  3410.  
  3411.    width is the width in bytes of the bit map.
  3412.  
  3413.    height is the height in bytes (pixel rows) of the bit map.
  3414.  
  3415. Return value
  3416.  
  3417.    none
  3418.  
  3419. Restrictions
  3420.  
  3421.    This routine has no effect in text video modes.
  3422.  
  3423. See also
  3424.  
  3425.    fg_drawmap, fg_getimage
  3426.  
  3427. Examples
  3428.  
  3429.    9-17, 9-18
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.  
  3441.  
  3442.  
  3443.  
  3444.  
  3445.  
  3446.  
  3447.                                       54
  3448. fg_getmaxx
  3449.  
  3450.  
  3451. Prototype
  3452.  
  3453.    int fg_getmaxx (void);
  3454.  
  3455. Description
  3456.  
  3457.    The fg_getmaxx routine returns the maximum x coordinate in screen space
  3458.    when used in a graphics video mode.  It returns the maximum column number
  3459.    in character space when used in a text mode.  In either case, the maximum x
  3460.    coordinate is one less than the horizontal screen resolution.
  3461.  
  3462. Parameters
  3463.  
  3464.    none
  3465.  
  3466. Return value
  3467.  
  3468.    The maximum x coordinate.
  3469.  
  3470. Restrictions
  3471.  
  3472.    none
  3473.  
  3474. See also
  3475.  
  3476.    fg_getmaxy
  3477.  
  3478. Examples
  3479.  
  3480.    4-1, 4-2
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.                                       55
  3507. fg_getmaxy
  3508.  
  3509.  
  3510. Prototype
  3511.  
  3512.    int fg_getmaxy (void);
  3513.  
  3514. Description
  3515.  
  3516.    The fg_getmaxy routine returns the maximum y coordinate in screen space
  3517.    when used in a graphics video mode.  It returns the maximum row number in
  3518.    character space when used in a text mode.  In either case, the maximum y
  3519.    coordinate is one less than the vertical screen resolution.
  3520.  
  3521. Parameters
  3522.  
  3523.    none
  3524.  
  3525. Return value
  3526.  
  3527.    The maximum y coordinate.
  3528.  
  3529. Restrictions
  3530.  
  3531.    none
  3532.  
  3533. See also
  3534.  
  3535.    fg_getmaxx
  3536.  
  3537. Examples
  3538.  
  3539.    4-1, 4-2
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.                                       56
  3566. fg_getmode
  3567.  
  3568.  
  3569. Prototype
  3570.  
  3571.    int fg_getmode (void);
  3572.  
  3573. Description
  3574.  
  3575.    The fg_getmode routine returns the current video mode number.  It is
  3576.    typically one of the first Fastgraph routines called in a program.  The
  3577.    value returned by fg_getmode can be retained to restore the original video
  3578.    mode when a program transfers control back to DOS.
  3579.  
  3580. Parameters
  3581.  
  3582.    none
  3583.  
  3584. Return value
  3585.  
  3586.    The current video mode number, between 0 and 21.  Refer to the description
  3587.    of the fg_setmode routine for descriptions of each video mode.
  3588.  
  3589. Restrictions
  3590.  
  3591.    none
  3592.  
  3593. See also
  3594.  
  3595.    fg_setmode
  3596.  
  3597. Examples
  3598.  
  3599.    3-3, 3-4, 3-5, 3-6, 3-7, 3-8
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.                                       57
  3625. fg_getpage
  3626.  
  3627.  
  3628. Prototype
  3629.  
  3630.    int fg_getpage (void);
  3631.  
  3632. Description
  3633.  
  3634.    The fg_getpage routine returns the active video page number (as set in the
  3635.    most recent call to fg_setpage).
  3636.  
  3637. Parameters
  3638.  
  3639.    none
  3640.  
  3641. Return value
  3642.  
  3643.    The number of the active video page, between 0 and 15.
  3644.  
  3645. Restrictions
  3646.  
  3647.    none
  3648.  
  3649. See also
  3650.  
  3651.    fg_setpage
  3652.  
  3653. Examples
  3654.  
  3655.    8-8
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.                                       58
  3684. fg_getpixel
  3685.  
  3686.  
  3687. Prototype
  3688.  
  3689.    int fg_getpixel (int ix, int iy);
  3690.  
  3691. Description
  3692.  
  3693.    The fg_getpixel routine returns the color value of a specified pixel.
  3694.  
  3695. Parameters
  3696.  
  3697.    ix is the pixel's screen space x coordinate.
  3698.  
  3699.    iy is the pixel's screen space y coordinate.
  3700.  
  3701. Return value
  3702.  
  3703.    The color value of the pixel, between 0 and one less than the number of
  3704.    colors available in the current video mode.  In text modes, fg_getpixel
  3705.    always returns zero.
  3706.  
  3707. Restrictions
  3708.  
  3709.    none
  3710.  
  3711. See also
  3712.  
  3713.    fg_point, fg_pointw
  3714.  
  3715. Examples
  3716.  
  3717.    6-1
  3718.  
  3719.  
  3720.  
  3721.  
  3722.  
  3723.  
  3724.  
  3725.  
  3726.  
  3727.  
  3728.  
  3729.  
  3730.  
  3731.  
  3732.  
  3733.  
  3734.  
  3735.  
  3736.  
  3737.  
  3738.  
  3739.  
  3740.  
  3741.  
  3742.                                       59
  3743. fg_getrgb
  3744.  
  3745.  
  3746. Prototype
  3747.  
  3748.    void fg_getrgb (int number, int *red, int *green, int *blue);
  3749.  
  3750. Description
  3751.  
  3752.    The fg_getrgb routine returns the red, green, and blue color components for
  3753.    a specified video DAC register.  Each color component is a value between 0
  3754.    and 63; increasing values produce more intense colors.
  3755.  
  3756. Parameters
  3757.  
  3758.    number is the video DAC register number.  It must be between 0 and 15 in
  3759.    video modes 17 and 18, or between 0 and 255 in modes 19 through 21.
  3760.  
  3761.    red, green, and blue respectively receive the red, green, and blue
  3762.    components of the specified video DAC register.
  3763.  
  3764. Return value
  3765.  
  3766.    none
  3767.  
  3768. Restrictions
  3769.  
  3770.    This routine has no effect in text video modes, or in any graphics video
  3771.    mode numbered 16 or below (because these video modes do not use DAC
  3772.    registers).
  3773.  
  3774. See also
  3775.  
  3776.    fg_palette, fg_setrgb
  3777.  
  3778. Examples
  3779.  
  3780.    5-11
  3781.  
  3782.  
  3783.  
  3784.  
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.                                       60
  3802. fg_getvpage
  3803.  
  3804.  
  3805. Prototype
  3806.  
  3807.    int fg_getvpage (void);
  3808.  
  3809. Description
  3810.  
  3811.    The fg_getvpage routine returns the visual video page number (as set in the
  3812.    most recent call to fg_setvpage).
  3813.  
  3814. Parameters
  3815.  
  3816.    none
  3817.  
  3818. Return value
  3819.  
  3820.    The number of the visual video page, between 0 and 15.
  3821.  
  3822. Restrictions
  3823.  
  3824.    none
  3825.  
  3826. See also
  3827.  
  3828.    fg_setvpage
  3829.  
  3830. Examples
  3831.  
  3832.    8-8
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847.  
  3848.  
  3849.  
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.  
  3859.  
  3860.                                       61
  3861. fg_getworld
  3862.  
  3863.  
  3864. Prototype
  3865.  
  3866.    void fg_getworld (double *xmin, double *xmax, double *ymin, double *ymax);
  3867.  
  3868. Description
  3869.  
  3870.    The fg_getworld routine returns the current world space limits, as defined
  3871.    in the most recent call to fg_setworld.
  3872.  
  3873. Parameters
  3874.  
  3875.    xmin receives the world space coordinate of the screen's left edge.
  3876.  
  3877.    xmax receives the world space coordinate of the screen's right edge.
  3878.  
  3879.    ymin receives the world space coordinate of the screen's top edge.
  3880.  
  3881.    ymax receives the world space coordinate of the screen's bottom edge.
  3882.  
  3883. Return value
  3884.  
  3885.    none
  3886.  
  3887. Restrictions
  3888.  
  3889.    This routine is not available in Fastgraph/Light.
  3890.  
  3891. See also
  3892.  
  3893.    fg_setworld
  3894.  
  3895. Examples
  3896.  
  3897.    4-3
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.                                       62
  3920. fg_getxjoy
  3921.  
  3922.  
  3923. Prototype
  3924.  
  3925.    int fg_getxjoy (int n);
  3926.  
  3927. Description
  3928.  
  3929.    The fg_getxjoy routine returns the horizontal coordinate position of the
  3930.    specified joystick.  The actual coordinates depend on the processor speed
  3931.    and brand of joystick used.
  3932.  
  3933. Parameters
  3934.  
  3935.    n specifies the joystick number, either 1 or 2.
  3936.  
  3937. Return value
  3938.  
  3939.    If the return value is positive, it represents the current horizontal
  3940.    coordinate position of the requested joystick.  If the return value is -1,
  3941.    it means the requested joystick has not been initialized or is not present.
  3942.  
  3943. Restrictions
  3944.  
  3945.    Before using this routine, you must use the fg_initjoy routine to
  3946.    initialize the requested joystick.
  3947.  
  3948. See also
  3949.  
  3950.    fg_button, fg_getyjoy, fg_initjoy, fg_intjoy
  3951.  
  3952. Examples
  3953.  
  3954.    12-11
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.                                       63
  3979. fg_getxpos
  3980.  
  3981.  
  3982. Prototype
  3983.  
  3984.    int fg_getxpos (void);
  3985.  
  3986. Description
  3987.  
  3988.    The fg_getxpos routine returns the screen space x coordinate of the
  3989.    graphics cursor position.
  3990.  
  3991. Parameters
  3992.  
  3993.    none
  3994.  
  3995. Return value
  3996.  
  3997.    The x coordinate of graphics cursor position.
  3998.  
  3999. Restrictions
  4000.  
  4001.    none
  4002.  
  4003. See also
  4004.  
  4005.    fg_getypos
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.                                       64
  4038. fg_getyjoy
  4039.  
  4040.  
  4041. Prototype
  4042.  
  4043.    int fg_getyjoy (int n);
  4044.  
  4045. Description
  4046.  
  4047.    The fg_getyjoy routine returns the vertical coordinate position of the
  4048.    specified joystick.  The actual coordinates depend on the processor speed
  4049.    and brand of joystick used.
  4050.  
  4051. Parameters
  4052.  
  4053.    n specifies the joystick number, either 1 or 2.
  4054.  
  4055. Return value
  4056.  
  4057.    If the return value is positive, it represents the current vertical
  4058.    coordinate position of the requested joystick.  If the return value is -1,
  4059.    it means the requested joystick has not been initialized or is not present.
  4060.  
  4061. Restrictions
  4062.  
  4063.    Before using this routine, you must use the fg_initjoy routine to
  4064.    initialize the requested joystick.
  4065.  
  4066. See also
  4067.  
  4068.    fg_button, fg_getxjoy, fg_initjoy, fg_intjoy
  4069.  
  4070. Examples
  4071.  
  4072.    12-11
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.                                       65
  4097. fg_getypos
  4098.  
  4099.  
  4100. Prototype
  4101.  
  4102.    int fg_getypos (void);
  4103.  
  4104. Description
  4105.  
  4106.    The fg_getypos routine returns the screen space y coordinate of the
  4107.    graphics cursor position.
  4108.  
  4109. Parameters
  4110.  
  4111.    none
  4112.  
  4113. Return value
  4114.  
  4115.    The y coordinate of graphics cursor position.
  4116.  
  4117. Restrictions
  4118.  
  4119.    none
  4120.  
  4121. See also
  4122.  
  4123.    fg_getxpos
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.                                       66
  4156. fg_hush
  4157.  
  4158.  
  4159. Prototype
  4160.  
  4161.    void fg_hush (void);
  4162.  
  4163. Description
  4164.  
  4165.    The fg_hush routine immediately stops asynchronous sound started with the
  4166.    fg_musicb, fg_sounds, or fg_voices routines.  It has no effect if there is
  4167.    no asynchronous sound in progress.
  4168.  
  4169. Parameters
  4170.  
  4171.    none
  4172.  
  4173. Return value
  4174.  
  4175.    none
  4176.  
  4177. Restrictions
  4178.  
  4179.    none
  4180.  
  4181. See also
  4182.  
  4183.    fg_hushnext, fg_musicb, fg_sounds, fg_voices
  4184.  
  4185. Examples
  4186.  
  4187.    13-7
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.                                       67
  4215. fg_hushnext
  4216.  
  4217.  
  4218. Prototype
  4219.  
  4220.    void fg_hushnext (void);
  4221.  
  4222. Description
  4223.  
  4224.    The fg_hushnext routine stops asynchronous sound started with the
  4225.    fg_musicb, fg_sounds, or fg_voices routines, but not until the current
  4226.    repetition finishes.  It has no effect if there is no asynchronous sound in
  4227.    progress.
  4228.  
  4229. Parameters
  4230.  
  4231.    none
  4232.  
  4233. Return value
  4234.  
  4235.    none
  4236.  
  4237. Restrictions
  4238.  
  4239.    This routine has no effect unless the asynchronous sound is continuous.
  4240.  
  4241. See also
  4242.  
  4243.    fg_hush, fg_musicb, fg_sounds, fg_voices
  4244.  
  4245. Examples
  4246.  
  4247.    13-7
  4248.  
  4249.  
  4250.  
  4251.  
  4252.  
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.                                       68
  4274. fg_initjoy
  4275.  
  4276.  
  4277. Prototype
  4278.  
  4279.    int fg_initjoy (int n);
  4280.  
  4281. Description
  4282.  
  4283.    The fg_initjoy routine initializes either joystick and must be called
  4284.    before using fg_getxjoy, fg_getyjoy, or fg_intjoy.
  4285.  
  4286. Parameters
  4287.  
  4288.    n specifies the joystick number, either 1 or 2.
  4289.  
  4290. Return value
  4291.  
  4292.    If the return value is 0, it means the joystick initialization was
  4293.    successful.  If it is -1, it means the machine has no game port, or the
  4294.    requested joystick is not connected to the game port.
  4295.  
  4296. Restrictions
  4297.  
  4298.    When you call fg_initjoy, Fastgraph assumes the requested joystick is
  4299.    centered.
  4300.  
  4301. See also
  4302.  
  4303.    fg_button, fg_getxjoy, fg_getyjoy, fg_intjoy
  4304.  
  4305. Examples
  4306.  
  4307.    12-10, 12-11, 12-12
  4308.  
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.  
  4323.  
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.  
  4330.  
  4331.  
  4332.                                       69
  4333. fg_initw
  4334.  
  4335.  
  4336. Prototype
  4337.  
  4338.    void fg_initw (void);
  4339.  
  4340. Description
  4341.  
  4342.    The fg_initw routine initializes Fastgraph's internal parameters for world
  4343.    space.  This routine must be called once, before any other routine that
  4344.    uses world space coordinates.
  4345.  
  4346. Parameters
  4347.  
  4348.    none
  4349.  
  4350. Return value
  4351.  
  4352.    none
  4353.  
  4354. Restrictions
  4355.  
  4356.    This routine is not available in Fastgraph/Light.
  4357.  
  4358. Examples
  4359.  
  4360.    4-3, 6-4, 6-8, 7-7, 7-8, 7-9, 7-10
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.  
  4375.  
  4376.  
  4377.  
  4378.  
  4379.  
  4380.  
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.  
  4388.  
  4389.  
  4390.  
  4391.                                       70
  4392. fg_intjoy
  4393.  
  4394.  
  4395. Prototype
  4396.  
  4397.    void fg_intjoy (int n, char *key, char *aux);
  4398.  
  4399. Description
  4400.  
  4401.    The fg_intjoy routine returns the standard and extended keyboard codes
  4402.    analogous to the current position and button status of the specified
  4403.    joystick.
  4404.  
  4405. Parameters
  4406.  
  4407.    n specifies the joystick number, either 1 or 2.
  4408.  
  4409.    key receives the joystick's button status.  If any button on the requested
  4410.    joystick is pressed, key is set to 13, the standard keyboard code for the
  4411.    Enter key.  If no buttons are pressed, key is set to zero.  In QuickBASIC,
  4412.    you must explicitly declare key as a fixed-length string variable of length
  4413.    1.
  4414.  
  4415.    aux receives the joystick's analog position, as listed below.  In
  4416.    QuickBASIC, you must explicitly declare aux as a fixed-length string
  4417.    variable of length 1.
  4418.  
  4419.  
  4420.            joystick position  corresponding key  extended key code
  4421.  
  4422.            up and left        Home               71
  4423.            up                 up arrow           72
  4424.            up and right       PgUp               73
  4425.            left               left arrow         75
  4426.            centered           (no action)         0
  4427.            right              right arrow        77
  4428.            down and left      End                79
  4429.            down               down arrow         80
  4430.            down and right     PgDn               81
  4431.  
  4432.  
  4433.    If the requested joystick has not been initialized, both key and aux will
  4434.    be set to zero.
  4435.  
  4436. Return value
  4437.  
  4438.    none
  4439.  
  4440. Restrictions
  4441.  
  4442.    Before using this routine, you must use the fg_initjoy routine to
  4443.    initialize the requested joystick.
  4444.  
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.                                       71
  4451. fg_intjoy (continued)
  4452.  
  4453.  
  4454. See also
  4455.  
  4456.    fg_button, fg_getxjoy, fg_getyjoy, fg_initjoy, fg_intkey
  4457.  
  4458. Examples
  4459.  
  4460.    12-12
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.                                       72
  4510. fg_intkey
  4511.  
  4512.  
  4513. Prototype
  4514.  
  4515.    void fg_intkey (unsigned char *key, unsigned char *aux);
  4516.  
  4517. Description
  4518.  
  4519.    The fg_intkey routine reads the next entry from the BIOS keyboard buffer
  4520.    (without echo) and returns the keystroke's standard or extended keyboard
  4521.    code (a list of these appears in chapter 12 of the Fastgraph User's Guide).
  4522.    It is similar to fg_getkey, but it does not wait for a keystroke if the
  4523.    keyboard buffer is empty.
  4524.  
  4525. Parameters
  4526.  
  4527.    key receives the keystroke's standard keyboard code if it represents a
  4528.    standard character.  If the keystroke represents an extended character, key
  4529.    will be set to zero.  In QuickBASIC, you must explicitly declare key as a
  4530.    fixed-length string variable of length 1.
  4531.  
  4532.    aux receives the keystroke's extended keyboard code if it represents an
  4533.    extended character.  If the keystroke represents a standard character, aux
  4534.    will be set to zero.  In QuickBASIC, you must explicitly declare aux as a
  4535.    fixed-length string variable of length 1.
  4536.  
  4537.    If the BIOS keyboard buffer is empty, both key and aux will be set to zero.
  4538.  
  4539. Return value
  4540.  
  4541.    none
  4542.  
  4543. Restrictions
  4544.  
  4545.    none
  4546.  
  4547. See also
  4548.  
  4549.    fg_getkey, fg_intjoy, fg_waitkey
  4550.  
  4551. Examples
  4552.  
  4553.    12-2, 13-7, 14-1, 14-3
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.                                       73
  4569. fg_locate
  4570.  
  4571.  
  4572. Prototype
  4573.  
  4574.    void fg_locate (int row, int column);
  4575.  
  4576. Description
  4577.  
  4578.    The fg_locate routine changes the text cursor position for the active
  4579.    display page.  The fg_setmode routine sets each page's text cursor position
  4580.    to (0,0).
  4581.  
  4582. Parameters
  4583.  
  4584.    row is the text cursor's destination row number, between 0 and 24 (0 and 29
  4585.    for VGA graphics modes 17 and 18).
  4586.  
  4587.    column is text cursor's destination column number, between 0 and 39 for 40-
  4588.    column modes, or between 0 and 79 for 80-column modes.
  4589.  
  4590. Return value
  4591.  
  4592.    none
  4593.  
  4594. Restrictions
  4595.  
  4596.    The first eight video pages (0 to 7) each have their own text cursor.  The
  4597.    last eight video pages (8 to 15) respectively share the same text cursor
  4598.    positions as the first eight pages.  For example, changing the text cursor
  4599.    position on video page 9 also changes its position on video page 1.
  4600.  
  4601. See also
  4602.  
  4603.    fg_where
  4604.  
  4605. Examples
  4606.  
  4607.    7-1 to 7-7
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.  
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.                                       74
  4628. fg_measure
  4629.  
  4630.  
  4631. Prototype
  4632.  
  4633.    int fg_measure (void);
  4634.  
  4635. Description
  4636.  
  4637.    The fg_measure routine returns the approximate number of delay units per
  4638.    clock tick.  This quantity is proportional to the system's processor speed.
  4639.    Delay units are used by the fg_stall routine.
  4640.  
  4641. Parameters
  4642.  
  4643.    none
  4644.  
  4645. Return value
  4646.  
  4647.    The approximate number of delay units per clock tick.  Typical values for
  4648.    some common systems are:
  4649.  
  4650.  
  4651.                          system      delay units
  4652.                           type     per clock tick
  4653.  
  4654.                      Tandy 1000 HX        675
  4655.                      10 MHz 80286       3,000
  4656.                      25 MHz 80386      11,000
  4657.  
  4658.  
  4659. Restrictions
  4660.  
  4661.    none
  4662.  
  4663. See also
  4664.  
  4665.    fg_stall
  4666.  
  4667. Examples
  4668.  
  4669.    14-3
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.                                       75
  4687. fg_memavail
  4688.  
  4689.  
  4690. Prototype
  4691.  
  4692.    long fg_memavail (void);
  4693.  
  4694. Description
  4695.  
  4696.    The fg_memavail routine determines the amount of memory available to DOS.
  4697.  
  4698. Parameters
  4699.  
  4700.    none
  4701.  
  4702. Return value
  4703.  
  4704.    The amount of memory (in bytes) available to DOS.
  4705.  
  4706. Restrictions
  4707.  
  4708.    none
  4709.  
  4710. Examples
  4711.  
  4712.    15-1
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.                                       76
  4746. fg_mousebut
  4747.  
  4748.  
  4749. Prototype
  4750.  
  4751.    void fg_mousebut (int number, int *count, int *lastx, int *lasty);
  4752.  
  4753. Description
  4754.  
  4755.    The fg_mousebut routine returns information about mouse button press or
  4756.    release counts, as well as the mouse cursor position at the time of the
  4757.    last button press or release.
  4758.  
  4759. Parameters
  4760.  
  4761.    number is the mouse button for which to report information (1 means the
  4762.    left button, 2 the right button, and 3 the middle button).  If number is
  4763.    positive, button press counts will be reported.  If it is negative, release
  4764.    counts will be reported.
  4765.  
  4766.    count receives the number of press or release counts for the requested
  4767.    button since the last check, or since calling the fg_mouseini routine.
  4768.  
  4769.    lastx receives the x coordinate (in screen space) of the mouse cursor
  4770.    position at the time of the last press or release of the requested button.
  4771.    If count is zero, lastx is also set to zero.
  4772.  
  4773.    lasty receives the y coordinate (in screen space) of the mouse cursor
  4774.    position at the time of the last press or release of the requested button.
  4775.    If count is zero, lasty is also set to zero.
  4776.  
  4777. Return value
  4778.  
  4779.    none
  4780.  
  4781. Restrictions
  4782.  
  4783.    none
  4784.  
  4785. See also
  4786.  
  4787.    fg_mousepos
  4788.  
  4789. Examples
  4790.  
  4791.    12-7
  4792.  
  4793.  
  4794.  
  4795.  
  4796.  
  4797.  
  4798.  
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.                                       77
  4805. fg_mousecur
  4806.  
  4807.  
  4808. Prototype
  4809.  
  4810.    void fg_mousecur (int screen_mask, int cursor_mask);
  4811.  
  4812. Description
  4813.  
  4814.    The fg_mousecur routine defines the appearance of the mouse cursor in text
  4815.    video modes.  Refer to chapter 12 of the Fastgraph User's Guide for
  4816.    complete information about defining the mouse cursor in text modes.
  4817.  
  4818. Parameters
  4819.  
  4820.    screen_mask defines the screen mask.  When you position the mouse over a
  4821.    specific character cell, the mouse driver logically ANDs the screen mask
  4822.    with the existing contents of that cell.
  4823.  
  4824.    cursor_mask defines the cursor mask.  After logically ANDing the screen
  4825.    mask with the contents of a character cell, the mouse driver XORs the
  4826.    cursor mask with the result to produce the mouse cursor.
  4827.  
  4828.    The binary structure of screen_mask and cursor_mask is:
  4829.  
  4830.  
  4831.                          bits      meaning
  4832.  
  4833.                         0 to 7     ASCII character value
  4834.                         8 to 11    foreground color
  4835.                        12 to 14    background color
  4836.                           15       blink
  4837.  
  4838.  
  4839. Return value
  4840.  
  4841.    none
  4842.  
  4843. Restrictions
  4844.  
  4845.    This routine has no effect in graphics video modes.
  4846.  
  4847. See also
  4848.  
  4849.    fg_mouseini, fg_mouseptr, fg_mousevis
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.                                       78
  4864. fg_mousecur (continued)
  4865.  
  4866.  
  4867. Examples
  4868.  
  4869.    12-8
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894.  
  4895.  
  4896.  
  4897.  
  4898.  
  4899.  
  4900.  
  4901.  
  4902.  
  4903.  
  4904.  
  4905.  
  4906.  
  4907.  
  4908.  
  4909.  
  4910.  
  4911.  
  4912.  
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.                                       79
  4923. fg_mouseini
  4924.  
  4925.  
  4926. Prototype
  4927.  
  4928.    int fg_mouseini (void);
  4929.  
  4930. Description
  4931.  
  4932.    The fg_mouseini routine initializes the mouse and must be called before any
  4933.    of Fastgraph's other mouse support routines.
  4934.  
  4935. Parameters
  4936.  
  4937.    none
  4938.  
  4939. Return value
  4940.  
  4941.    If the return value is positive, it indicates the number of buttons on the
  4942.    mouse being used (2 or 3).  If the return value is -1, it means the
  4943.    initialization failed because the mouse driver has not been loaded or the
  4944.    mouse is not physically connected.
  4945.  
  4946. Restrictions
  4947.  
  4948.    There is no mouse support available in video modes 20 and 21.  The
  4949.    fg_mouseini routine will always return -1 when used in these video modes.
  4950.  
  4951. See also
  4952.  
  4953.    fg_mousebut, fg_mousecur, fg_mouselim, fg_mousemov, fg_mousepos,
  4954.    fg_mouseptr, fg_mousespd, fg_mousevis
  4955.  
  4956. Examples
  4957.  
  4958.    12-5, 12-6, 12-7, 12-8, 12-9
  4959.  
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.                                       80
  4982. fg_mouselim
  4983.  
  4984.  
  4985. Prototype
  4986.  
  4987.    void fg_mouselim (int minx, int maxx, int miny, int maxy);
  4988.  
  4989. Description
  4990.  
  4991.    The fg_mouselim routine defines the rectangular area in which the mouse
  4992.    cursor may move.  In graphics modes, the area is defined in screen space
  4993.    coordinates.  In text modes, it is defined in rows and columns.
  4994.  
  4995. Parameters
  4996.  
  4997.    minx is the x coordinate of the area's left edge.
  4998.  
  4999.    maxx is the x coordinate of the area's right edge.  It must be greater than
  5000.    or equal to the value of minx.
  5001.  
  5002.    miny is the y coordinate of the area's top edge.
  5003.  
  5004.    maxy is the y coordinate of the area's bottom edge.  It must be greater
  5005.    than or equal to the value of miny.
  5006.  
  5007. Return value
  5008.  
  5009.    none
  5010.  
  5011. Restrictions
  5012.  
  5013.    none
  5014.  
  5015. See also
  5016.  
  5017.    fg_mouseini, fg_mousemov
  5018.  
  5019. Examples
  5020.  
  5021.    12-6
  5022.  
  5023.  
  5024.  
  5025.  
  5026.  
  5027.  
  5028.  
  5029.  
  5030.  
  5031.  
  5032.  
  5033.  
  5034.  
  5035.  
  5036.  
  5037.  
  5038.  
  5039.  
  5040.                                       81
  5041. fg_mousemov
  5042.  
  5043.  
  5044. Prototype
  5045.  
  5046.    void fg_mousemov (int ix, int iy);
  5047.  
  5048. Description
  5049.  
  5050.    The fg_mousemov routine moves the mouse cursor to the specified character
  5051.    cell (in text modes) or screen space position (in graphics modes).  The
  5052.    mouse cursor is moved whether or not it is currently visible.
  5053.  
  5054. Parameters
  5055.  
  5056.    ix is the x coordinate of the mouse cursor position.
  5057.  
  5058.    iy is the y coordinate of the mouse cursor position.
  5059.  
  5060. Return value
  5061.  
  5062.    none
  5063.  
  5064. Restrictions
  5065.  
  5066.    If you attempt to move the mouse cursor outside the area defined by
  5067.    fg_mouselim, the fg_mousemov routine just positions the cursor at the
  5068.    nearest point possible within that area.
  5069.  
  5070. See also
  5071.  
  5072.    fg_mouseini, fg_mouselim
  5073.  
  5074. Examples
  5075.  
  5076.    12-6
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.                                       82
  5100. fg_mousepos
  5101.  
  5102. Prototype
  5103.  
  5104.    void fg_mousepos (int *ix, int *iy, int *buttons);
  5105.  
  5106. Description
  5107.  
  5108.    The fg_mousepos routine returns the current mouse position and button
  5109.    status.  In graphics modes, the position is defined in screen space
  5110.    coordinates.  In text modes, it is defined in rows and columns.
  5111.  
  5112. Parameters
  5113.  
  5114.    ix receives the x coordinate of the mouse cursor position.
  5115.  
  5116.    iy receives the y coordinate of the mouse cursor position.
  5117.  
  5118.    buttons receives a bit mask representing the button status, where each bit
  5119.    is set if the corresponding button is pressed.  Bit 0 corresponds to the
  5120.    left button, bit 1 to the right button, and bit 2 to the middle button.
  5121.  
  5122. Return value
  5123.  
  5124.    none
  5125.  
  5126. Restrictions
  5127.  
  5128.    none
  5129.  
  5130. See also
  5131.  
  5132.    fg_mousebut, fg_mouseini
  5133.  
  5134. Examples
  5135.  
  5136.    12-7
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.                                       83
  5159. fg_mouseptr
  5160.  
  5161.  
  5162. Prototype
  5163.  
  5164.    void fg_mouseptr (int *masks, int xoffset, int yoffset);
  5165.  
  5166. Description
  5167.  
  5168.    The fg_mouseptr routine defines the shape and appearance of the mouse
  5169.    cursor in graphics video modes.  Refer to chapter 12 of the Fastgraph
  5170.    User's Guide for complete information about defining the mouse cursor in
  5171.    graphics modes.
  5172.  
  5173. Parameters
  5174.  
  5175.    masks is a 32-element array containing the 16-element screen mask followed
  5176.    by the 16-element cursor mask.  The mouse driver displays the mouse cursor
  5177.    by logically ANDing video memory with the screen mask, and then XORing that
  5178.    result with the cursor mask.  The first item of each mask corresponds to
  5179.    the top row of the mouse cursor.  The following table summarizes the cursor
  5180.    appearance for all possible combinations of mask bits.
  5181.  
  5182.  
  5183.            screen mask bit  cursor mask bit  resulting cursor pixel
  5184.  
  5185.                   0                0                  black
  5186.                   0                1                  white
  5187.                   1                0                unchanged
  5188.                   1                1                 inverted
  5189.  
  5190.  
  5191.    xoffset is the x coordinate of the mouse cursor "hot spot" relative to the
  5192.    upper left corner of the mouse cursor.
  5193.  
  5194.    yoffset is the y coordinate of the mouse cursor "hot spot" relative to the
  5195.    upper left corner of the mouse cursor.
  5196.  
  5197. Return value
  5198.  
  5199.    none
  5200.  
  5201. Restrictions
  5202.  
  5203.    This routine has no effect in text video modes.
  5204.  
  5205. See also
  5206.  
  5207.    fg_mousecur, fg_mouseini, fg_mousevis
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.                                       84
  5218. fg_mouseptr (continued)
  5219.  
  5220.  
  5221. Examples
  5222.  
  5223.    12-9
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.                                       85
  5277. fg_mousespd
  5278.  
  5279.  
  5280. Prototype
  5281.  
  5282.    void fg_mousespd (int xmickeys, int ymickeys);
  5283.  
  5284. Description
  5285.  
  5286.    The fg_mousespd routine defines the number of mickey units per eight pixels
  5287.    of cursor movement (one mickey unit equals 1/200 of an inch).  This
  5288.    effectively controls the speed at which the mouse cursor moves relative to
  5289.    the movement of the mouse itself.
  5290.  
  5291. Parameters
  5292.  
  5293.    xmickeys is the number of mickey units per eight pixels of horizontal mouse
  5294.    cursor movement (the default is 8).
  5295.  
  5296.    ymickeys is the number of mickey units per eight pixels of vertical mouse
  5297.    cursor movement (the default is 16).
  5298.  
  5299. Return value
  5300.  
  5301.    none
  5302.  
  5303. Restrictions
  5304.  
  5305.    none
  5306.  
  5307. See also
  5308.  
  5309.    fg_mouseini
  5310.  
  5311. Examples
  5312.  
  5313.    12-6
  5314.  
  5315.  
  5316.  
  5317.  
  5318.  
  5319.  
  5320.  
  5321.  
  5322.  
  5323.  
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.                                       86
  5336. fg_mousevis
  5337.  
  5338.  
  5339. Prototype
  5340.  
  5341.    void fg_mousevis (int state);
  5342.  
  5343. Description
  5344.  
  5345.    The fg_mousevis routine makes the mouse cursor visible or invisible.  After
  5346.    calling fg_mouseini, the mouse cursor is invisible.
  5347.  
  5348. Parameters
  5349.  
  5350.    state defines the mouse cursor visibility.  If state is 0, the mouse cursor
  5351.    is made invisible.  If it is 1, the mouse cursor is made visible.
  5352.  
  5353. Return value
  5354.  
  5355.    none
  5356.  
  5357. Restrictions
  5358.  
  5359.    none
  5360.  
  5361. See also
  5362.  
  5363.    fg_mouseini
  5364.  
  5365. Examples
  5366.  
  5367.    12-6, 12-7, 12-8, 12-9
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.                                       87
  5395. fg_move
  5396.  
  5397.  
  5398. Prototype
  5399.  
  5400.    void fg_move (int ix, int iy);
  5401.  
  5402. Description
  5403.  
  5404.    The fg_move routine establishes the graphics cursor position at an absolute
  5405.    screen space point.  The fg_setmode routine sets the graphics cursor
  5406.    position to (0,0).
  5407.  
  5408. Parameters
  5409.  
  5410.    ix is the screen space x coordinate of the graphics cursor's new position.
  5411.  
  5412.    iy is the screen space y coordinate of the graphics cursor's new position.
  5413.  
  5414. Return value
  5415.  
  5416.    none
  5417.  
  5418. Restrictions
  5419.  
  5420.    This routine has no effect in text video modes.
  5421.  
  5422. See also
  5423.  
  5424.    fg_moverel, fg_moverw, fg_movew
  5425.  
  5426. Examples
  5427.  
  5428.    6-2, 6-3, 6-5, 6-6, 6-9, 6-14, 9-1
  5429.  
  5430.  
  5431.  
  5432.  
  5433.  
  5434.  
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.                                       88
  5454. fg_moverel
  5455.  
  5456.  
  5457. Prototype
  5458.  
  5459.    void fg_moverel (int ix, int iy);
  5460.  
  5461. Description
  5462.  
  5463.    The fg_moverel routine establishes the graphics cursor position at a screen
  5464.    space point relative to the current position.
  5465.  
  5466. Parameters
  5467.  
  5468.    ix is the screen space x offset of the graphics cursor's new position.
  5469.  
  5470.    iy is the screen space y offset of the graphics cursor's new position.
  5471.  
  5472. Return value
  5473.  
  5474.    none
  5475.  
  5476. Restrictions
  5477.  
  5478.    This routine has no effect in text video modes.
  5479.  
  5480. See also
  5481.  
  5482.    fg_move, fg_moverw, fg_movew
  5483.  
  5484. Examples
  5485.  
  5486.    6-3
  5487.  
  5488.  
  5489.  
  5490.  
  5491.  
  5492.  
  5493.  
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500.  
  5501.  
  5502.  
  5503.  
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.  
  5510.  
  5511.  
  5512.                                       89
  5513. fg_moverw
  5514.  
  5515.  
  5516. Prototype
  5517.  
  5518.    void fg_moverw (double x, double y);
  5519.  
  5520. Description
  5521.  
  5522.    The fg_moverw routine establishes the graphics cursor position at a world
  5523.    space point relative to the current position.
  5524.  
  5525. Parameters
  5526.  
  5527.    x is the world space x offset of the graphics cursor's new position.
  5528.  
  5529.    y is the world space y offset of the graphics cursor's new position.
  5530.  
  5531. Return value
  5532.  
  5533.    none
  5534.  
  5535. Restrictions
  5536.  
  5537.    This routine is not available in Fastgraph/Light and has no effect in text
  5538.    video modes.
  5539.  
  5540. See also
  5541.  
  5542.    fg_move, fg_moverel, fg_movew
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.                                       90
  5572. fg_movew
  5573.  
  5574.  
  5575. Prototype
  5576.  
  5577.    void fg_movew (double x, double y);
  5578.  
  5579. Description
  5580.  
  5581.    The fg_movew routine establishes the graphics cursor position at an
  5582.    absolute world space point.  The fg_initw routine sets the graphics cursor
  5583.    position to (0.0,0.0).
  5584.  
  5585. Parameters
  5586.  
  5587.    x is the world space x coordinate of the graphics cursor's new position.
  5588.  
  5589.    y is the world space y coordinate of the graphics cursor's new position.
  5590.  
  5591. Return value
  5592.  
  5593.    none
  5594.  
  5595. Restrictions
  5596.  
  5597.    This routine is not available in Fastgraph/Light and has no effect in text
  5598.    video modes.
  5599.  
  5600. See also
  5601.  
  5602.    fg_move, fg_moverel, fg_moverw
  5603.  
  5604. Examples
  5605.  
  5606.    6-4, 6-8, 7-7, 7-8, 7-9, 7-10
  5607.  
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.  
  5616.  
  5617.  
  5618.  
  5619.  
  5620.  
  5621.  
  5622.  
  5623.  
  5624.  
  5625.  
  5626.  
  5627.  
  5628.  
  5629.  
  5630.                                       91
  5631. fg_music
  5632.  
  5633.  
  5634. Prototype
  5635.  
  5636.    void fg_music (char *music_string);
  5637.  
  5638. Description
  5639.  
  5640.    The fg_music routine uses the programmable timer to play a sequence of
  5641.    musical tones.
  5642.  
  5643. Parameters
  5644.  
  5645.    music_string is an arbitrary-length sequence of music commands, followed by
  5646.    a dollar-sign ($) terminator.  Music commands are summarized in the
  5647.    following table:
  5648.  
  5649.  
  5650.    command   meaning
  5651.  
  5652.    A thru G  Play the specified note in the current octave.
  5653.  
  5654.    #         May be appended to a note character (A through G) to make that
  5655.              note sharp.
  5656.  
  5657.    .         May be appended to a note character (A through G) or a sharp (#)
  5658.              to extend that note by half its normal length.  Multiple dots may
  5659.              be used, and each one will again extend the note by half as much
  5660.              as the previous extension.
  5661.  
  5662.    Ln        Set the length of subsequent notes and pauses.  The value of n is
  5663.              an integer between 1 and 64, where 1 indicates a whole note, 2 a
  5664.              half note, 4 a quarter note, and so forth.  If no L command is
  5665.              present, L4 is assumed.
  5666.  
  5667.    On        Set the octave for subsequent notes.  The value of n may be an
  5668.              integer between 0 and 6 to set a specific octave.  It can also be
  5669.              a plus (+) or minus (-) character to increment or decrement the
  5670.              current octave number.  Octave 4 contains middle C, and if no O
  5671.              command is present, O4 is assumed.
  5672.  
  5673.    P         Pause (rest) for the duration specified by the most recent L
  5674.              command.
  5675.  
  5676.    Sn        Set the amount of silence between notes.  The value of n is an
  5677.              integer between 0 and 2.  If n is 0, each note plays for the full
  5678.              period set by the L command (music legato).  If n is 1, each note
  5679.              plays for 7/8 the period set by the L command (music normal).  If
  5680.              n is 2, each note plays for 3/4 the period set by the L command
  5681.              (music staccato).  If no S command is present, S1 is assumed.
  5682.  
  5683.    Tn        Set the tempo of the music (the number of quarter notes per
  5684.              minute).  The value of n is an integer between 32 and 255.  If no
  5685.              T command is present, T120 is assumed.
  5686.  
  5687.  
  5688.  
  5689.                                       92
  5690. fg_music (continued)
  5691.  
  5692.  
  5693.    The fg_music routine ignores any other characters in music_string.  It also
  5694.    ignores command values outside the allowable range, such as T20 or O8.
  5695.  
  5696. Return value
  5697.  
  5698.    none
  5699.  
  5700. Restrictions
  5701.  
  5702.    This routine has no effect if there is asynchronous sound in progress.
  5703.  
  5704. See also
  5705.  
  5706.    fg_musicb
  5707.  
  5708. Examples
  5709.  
  5710.    13-3
  5711.  
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  
  5718.  
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.  
  5748.                                       93
  5749. fg_musicb
  5750.  
  5751.  
  5752. Prototype
  5753.  
  5754.    void fg_musicb (char *music_string, int ntimes);
  5755.  
  5756. Description
  5757.  
  5758.    The fg_musicb routine uses the programmable timer to play a sequence of
  5759.    musical tones, concurrent with other activity.
  5760.  
  5761. Parameters
  5762.  
  5763.    music_string is an arbitrary-length sequence of music commands, followed by
  5764.    a dollar-sign ($) terminator.  Refer to the description of the fg_music
  5765.    routine for a complete list of music commands.
  5766.  
  5767.    ntimes specifies the number of times to cycle through the music commands in
  5768.    music_string.  If ntimes is negative, the music will play repetitively
  5769.    until you stop it with the fg_hush or fg_hushnext routine.
  5770.  
  5771. Return value
  5772.  
  5773.    none
  5774.  
  5775. Restrictions
  5776.  
  5777.    This routine has no effect if there is asynchronous sound already in
  5778.    progress.  To allow for fast-tempo music, Fastgraph temporarily quadruples
  5779.    the clock tick interrupt rate from 18.2 to 72.8 ticks per second while
  5780.    producing asynchronous sound.  Because many disk controllers rely on the
  5781.    18.2 tick per second clock rate to synchronize disk accesses, your programs
  5782.    should not perform any disk operations when asynchronous sound is in
  5783.    progress.
  5784.  
  5785. See also
  5786.  
  5787.    fg_hush, fg_hushnext, fg_music, fg_playing
  5788.  
  5789. Examples
  5790.  
  5791.    13-6, 13-7
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.                                       94
  5808. fg_numlock
  5809.  
  5810.  
  5811. Prototype
  5812.  
  5813.    int fg_numlock (void);
  5814.  
  5815. Description
  5816.  
  5817.    The fg_numlock routine determines the state of the NumLock key.
  5818.  
  5819. Parameters
  5820.  
  5821.    none
  5822.  
  5823. Return value
  5824.  
  5825.    If the return value is 0, it means the NumLock key is off.  If it is 1, it
  5826.    means the NumLock key is on.
  5827.  
  5828. Restrictions
  5829.  
  5830.    none
  5831.  
  5832. See also
  5833.  
  5834.    fg_capslock, fg_scrlock, fg_setcaps, fg_setnum
  5835.  
  5836. Examples
  5837.  
  5838.    12-3
  5839.  
  5840.  
  5841.  
  5842.  
  5843.  
  5844.  
  5845.  
  5846.  
  5847.  
  5848.  
  5849.  
  5850.  
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.                                       95
  5867. fg_paint
  5868.  
  5869.  
  5870. Prototype
  5871.  
  5872.    void fg_paint (int ix, int iy);
  5873.  
  5874. Description
  5875.  
  5876.    The fg_paint routine fills an arbitrary closed region with the current
  5877.    color value.  The region is defined by specifying a screen space point
  5878.    within its interior.
  5879.  
  5880. Parameters
  5881.  
  5882.    ix is the screen space x coordinate of the interior point.
  5883.  
  5884.    iy is the screen space y coordinate of the interior point.
  5885.  
  5886. Return value
  5887.  
  5888.    none
  5889.  
  5890. Restrictions
  5891.  
  5892.    This routine has no effect in text video modes.  The screen edges are not
  5893.    considered region boundaries, and filling an open region will cause
  5894.    fg_paint to behave unpredictably.
  5895.  
  5896. See also
  5897.  
  5898.    fg_paintw
  5899.  
  5900. Examples
  5901.  
  5902.    6-14, 11-5
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.                                       96
  5926. fg_paintw
  5927.  
  5928.  
  5929. Prototype
  5930.  
  5931.    void fg_paintw (double x, double y);
  5932.  
  5933. Description
  5934.  
  5935.    The fg_paintw routine fills an arbitrary closed region with the current
  5936.    color value.  The region is defined by specifying a world space point
  5937.    within its interior.
  5938.  
  5939. Parameters
  5940.  
  5941.    x is the world space x coordinate of the interior point.
  5942.  
  5943.    y is the world space y coordinate of the interior point.
  5944.  
  5945. Return value
  5946.  
  5947.    none
  5948.  
  5949. Restrictions
  5950.  
  5951.    This routine is not available in Fastgraph/Light and has no effect in text
  5952.    video modes.  The screen edges are not considered region boundaries, and
  5953.    filling an open region will cause fg_paintw to behave unpredictably.
  5954.  
  5955. See also
  5956.  
  5957.    fg_paint
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.  
  5964.  
  5965.  
  5966.  
  5967.  
  5968.  
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.  
  5983.  
  5984.                                       97
  5985. fg_palette
  5986.  
  5987.  
  5988. Prototype
  5989.  
  5990.    void fg_palette (int number, int color);
  5991.  
  5992. Description
  5993.  
  5994.    The fg_palette routine has different functions depending on the current
  5995.    graphics video mode.  For CGA four-color modes (modes 4 and 5), it
  5996.    establishes the current palette and defines the background color for that
  5997.    palette.  In the CGA two-color mode (mode 6), it defines the foreground
  5998.    color.  For Tandy/PCjr, EGA, and VGA graphics modes (modes 9, 13, 14, 15,
  5999.    16, 17, and 18), it defines the value of a palette register.  For 256-color
  6000.    MCGA and VGA graphics modes (modes 19, 20, and 21), it defines the value of
  6001.    a video DAC register.
  6002.  
  6003. Parameters
  6004.  
  6005.    The meanings of the number and color parameters depend on the current video
  6006.    mode.  The following table summarizes the parameter meanings and legal
  6007.    values for each video mode.
  6008.  
  6009.  
  6010.    mode   number parameter (range)              color parameter (range)
  6011.  
  6012.    4, 5   CGA palette number (0 to 5)           background color (0 to 15)
  6013.    6      ignored                               foreground color (0 to 15)
  6014.    9      palette register number (0 to 15)     palette value (0 to 15)
  6015.    13, 14 palette register number (0 to 15)     palette value (0 to 23)
  6016.    15     palette register number (0,1,4,or 5)  palette value (0,8,or 24)
  6017.    16     palette register number (0 to 15)     palette value (0 to 63)
  6018.    17     palette register number (0 or 1)      video DAC register (0 to 15)
  6019.    18     palette register number (0 to 15)     video DAC register (0 to 15)
  6020.    19-21  video DAC register number (0 to 255)  DAC value (0 to 63)
  6021.  
  6022.  
  6023.    Refer to chapter 5 of the Fastgraph User's Guide for more specific
  6024.    information about the number and color parameters.
  6025.  
  6026. Return value
  6027.  
  6028.    none
  6029.  
  6030. Restrictions
  6031.  
  6032.    This routine has no effect in text video modes or Hercules graphics modes.
  6033.    Changing the foreground color (in mode 6) always works on true CGA
  6034.    adapters, but there are very few EGA and VGA adapters that correctly
  6035.    implement this capability in their mode 6 emulation.
  6036.  
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  
  6043.                                       98
  6044. fg_palette (continued)
  6045.  
  6046.  
  6047. See also
  6048.  
  6049.    fg_defcolor, fg_palettes, fg_setcolor, fg_setrgb
  6050.  
  6051. Examples
  6052.  
  6053.    5-1, 5-2, 5-3, 5-6, 5-7, 5-8, 5-9, 5-14, 9-14
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.  
  6078.  
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.  
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.                                       99
  6103. fg_palettes
  6104.  
  6105.  
  6106. Prototype
  6107.  
  6108.    void fg_palettes (int *color_array);
  6109.  
  6110. Description
  6111.  
  6112.    The fg_palettes routine defines all 16 palette registers (in Tandy/PCjr,
  6113.    EGA, and VGA graphics modes), or the first 16 video DAC registers (in 256-
  6114.    color MCGA and VGA graphics modes).
  6115.  
  6116. Parameters
  6117.  
  6118.    color_array is a 16-element array that contains the values to assign to the
  6119.    palette registers or video DAC registers.
  6120.  
  6121. Return value
  6122.  
  6123.    none
  6124.  
  6125. Restrictions
  6126.  
  6127.    This routine has no effect in text video modes, CGA graphics modes, or
  6128.    Hercules graphics modes.
  6129.  
  6130. See also
  6131.  
  6132.    fg_palette
  6133.  
  6134. Examples
  6135.  
  6136.    5-12
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.  
  6144.  
  6145.  
  6146.  
  6147.  
  6148.  
  6149.  
  6150.  
  6151.  
  6152.  
  6153.  
  6154.  
  6155.  
  6156.  
  6157.  
  6158.  
  6159.  
  6160.  
  6161.                                      100
  6162. fg_pan
  6163.  
  6164.  
  6165. Prototype
  6166.  
  6167.    void fg_pan (int ix, int iy);
  6168.  
  6169. Description
  6170.  
  6171.    The fg_pan routine changes the screen origin (the upper left corner of the
  6172.    screen) to the specified screen space coordinates.
  6173.  
  6174. Parameters
  6175.  
  6176.    ix is the new screen space x coordinate for the screen origin.
  6177.  
  6178.    iy is the new screen space y coordinate for the screen origin.
  6179.  
  6180. Return value
  6181.  
  6182.    none
  6183.  
  6184. Restrictions
  6185.  
  6186.    This routine has no effect in text video odes.  Because of hardware
  6187.    limitations, only certain coordinate positions can be used as the screen
  6188.    origin.  Fastgraph compensates for these restrictions by reducing ix and iy
  6189.    to values that are acceptable to the current video mode, as shown in the
  6190.    following table.
  6191.  
  6192.  
  6193.                             x will be reduced  y will be reduced
  6194.                 video mode  to a multiple of:  to a multiple of:
  6195.  
  6196.                    4, 5             8                  2
  6197.                      6             16                  2
  6198.                      9              4                  4
  6199.                     11              8                  4
  6200.                     12              4                2 or 3
  6201.                 19, 20, 21          4                  1
  6202.  
  6203.  
  6204. See also
  6205.  
  6206.    fg_panw
  6207.  
  6208. Examples
  6209.  
  6210.    11-6
  6211.  
  6212.  
  6213.  
  6214.  
  6215.  
  6216.  
  6217.  
  6218.  
  6219.  
  6220.                                      101
  6221. fg_panw
  6222.  
  6223.  
  6224. Prototype
  6225.  
  6226.    void fg_panw (double x, double y);
  6227.  
  6228. Description
  6229.  
  6230.    The fg_panw routine changes the screen origin (the upper left corner of the
  6231.    screen) to the specified world space coordinates.
  6232.  
  6233. Parameters
  6234.  
  6235.    x is the new world space x coordinate for the screen origin.
  6236.  
  6237.    y is the new world space y coordinate for the screen origin.
  6238.  
  6239. Return value
  6240.  
  6241.    none
  6242.  
  6243. Restrictions
  6244.  
  6245.    This routine is not available in Fastgraph/Light and has no effect in text
  6246.    video modes.  To compensate for the hardware limitations that restrict the
  6247.    screen origin coordinates (see the description of the fg_pan routine),
  6248.    Fastgraph reduces x and y to an acceptable screen space equivalent.
  6249.  
  6250. See also
  6251.  
  6252.    fg_pan
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.  
  6264.  
  6265.  
  6266.  
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.  
  6276.  
  6277.  
  6278.  
  6279.                                      102
  6280. fg_pattern
  6281.  
  6282.  
  6283. Prototype
  6284.  
  6285.    void fg_pattern (int index, int display_pattern);
  6286.  
  6287. Description
  6288.  
  6289.    The fg_pattern routine defines one of Fastgraph's 256 display patterns used
  6290.    with the fg_dispfile, fg_display, or fg_displayp routines.  When using
  6291.    these routines to display a pixel run map, Fastgraph will use the pattern
  6292.    associated with that color index instead of displaying the color itself.
  6293.    Refer to the Fastgraph User's Guide for more information about display
  6294.    patterns and their default values for each graphics video mode.
  6295.  
  6296. Parameters
  6297.  
  6298.    index is the number of the display pattern to define, between 0 and 255.
  6299.  
  6300.    display_pattern is a 16-bit value representing the actual display pattern.
  6301.    Its structure depends on the video mode, as summarized in the following
  6302.    table.
  6303.  
  6304.  
  6305.       video modes         pattern structure
  6306.  
  6307.       4, 5, 12            shift count (8 bits), four pixels (2 bits each)
  6308.       6, 11               shift count (8 bits), eight pixels (1 bit each)
  6309.       9                   shift count (8 bits), two pixels (4 bits each)
  6310.       13, 14, 15, 16, 18  unused (8 bits), two pixels (4 bits each)
  6311.       17                  unused (14 bits), two pixels (1 bit each)
  6312.  
  6313.  
  6314.    The shift count defines the number of bits that display_pattern is rotated
  6315.    left when applied to odd-numbered pixel rows, while the pixels are the
  6316.    actual color values replicated through the pixel run.  For the EGA and VGA
  6317.    graphics modes, an implied one pixel shift count is used.
  6318.  
  6319. Return value
  6320.  
  6321.    none
  6322.  
  6323. Restrictions
  6324.  
  6325.    This routine has no effect in text video modes or in 256-color graphics
  6326.    modes.
  6327.  
  6328. See also
  6329.  
  6330.    fg_dispfile, fg_display, fg_displayp
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.                                      103
  6339. fg_pattern (continued)
  6340.  
  6341.  
  6342. Examples
  6343.  
  6344.    9-14
  6345.  
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.  
  6359.  
  6360.  
  6361.  
  6362.  
  6363.  
  6364.  
  6365.  
  6366.  
  6367.  
  6368.  
  6369.  
  6370.  
  6371.  
  6372.  
  6373.  
  6374.  
  6375.  
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394.  
  6395.  
  6396.  
  6397.                                      104
  6398. fg_playing
  6399.  
  6400.  
  6401. Prototype
  6402.  
  6403.    int fg_playing (void);
  6404.  
  6405. Description
  6406.  
  6407.    The fg_playing routine determines whether or not there is any asynchronous
  6408.    sound in progress.
  6409.  
  6410. Parameters
  6411.  
  6412.    none
  6413.  
  6414. Return value
  6415.  
  6416.    If the return value is 0, it means there is no asynchronous sound in
  6417.    progress.  If it is 1, then there is asynchronous sound in progress.
  6418.  
  6419. Restrictions
  6420.  
  6421.    none
  6422.  
  6423. See also
  6424.  
  6425.    fg_musicb, fg_sounds, fg_voices
  6426.  
  6427. Examples
  6428.  
  6429.    13-4, 13-5, 13-6, 13-7
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.                                      105
  6457. fg_point
  6458.  
  6459.  
  6460. Prototype
  6461.  
  6462.    void fg_point (int ix, int iy);
  6463.  
  6464. Description
  6465.  
  6466.    The fg_point routine draws a point (displays a pixel) in screen space.
  6467.  
  6468. Parameters
  6469.  
  6470.    ix is the point's screen space x coordinate.
  6471.  
  6472.    iy is the point's screen space y coordinate.
  6473.  
  6474. Return value
  6475.  
  6476.    none
  6477.  
  6478. Restrictions
  6479.  
  6480.    This routine has no effect in text video modes.
  6481.  
  6482. See also
  6483.  
  6484.    fg_pointw
  6485.  
  6486. Examples
  6487.  
  6488.    6-1
  6489.  
  6490.  
  6491.  
  6492.  
  6493.  
  6494.  
  6495.  
  6496.  
  6497.  
  6498.  
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.  
  6507.  
  6508.  
  6509.  
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.                                      106
  6516. fg_pointw
  6517.  
  6518.  
  6519. Prototype
  6520.  
  6521.    void fg_pointw (double x, double y);
  6522.  
  6523. Description
  6524.  
  6525.    The fg_pointw routine draws a point (displays a pixel) in world space.
  6526.  
  6527. Parameters
  6528.  
  6529.    x is the point's world space x coordinate.
  6530.  
  6531.    y is the point's world space y coordinate.
  6532.  
  6533. Return value
  6534.  
  6535.    none
  6536.  
  6537. Restrictions
  6538.  
  6539.    This routine is not available in Fastgraph/Light and has no effect in text
  6540.    video modes.
  6541.  
  6542. See also
  6543.  
  6544.    fg_point
  6545.  
  6546.  
  6547.  
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.  
  6554.  
  6555.  
  6556.  
  6557.  
  6558.  
  6559.  
  6560.  
  6561.  
  6562.  
  6563.  
  6564.  
  6565.  
  6566.  
  6567.  
  6568.  
  6569.  
  6570.  
  6571.  
  6572.  
  6573.  
  6574.                                      107
  6575. fg_polygon
  6576.  
  6577.  
  6578. Prototype
  6579.  
  6580.    void fg_polygon (int *ix_array, int *iy_array, int n);
  6581.  
  6582. Description
  6583.  
  6584.    The fg_polygon routine draws an unfilled polygon in screen space, using two
  6585.    coordinate arrays to define the polygon vertices.  The drawing of the
  6586.    polygon begins at the graphics cursor position, through the vertices
  6587.    defined by the coordinate arrays, and finally back to the original graphics
  6588.    cursor position if necessary.
  6589.  
  6590. Parameters
  6591.  
  6592.    ix_array is an arbitrary-length array containing the screen space x
  6593.    coordinates of the polygon vertices.
  6594.  
  6595.    iy_array is an arbitrary-length array containing the screen space y
  6596.    coordinates of the polygon vertices.
  6597.  
  6598.    n is the number of vertices in the polygon.
  6599.  
  6600. Return value
  6601.  
  6602.    none
  6603.  
  6604. Restrictions
  6605.  
  6606.    This routine has no effect in text video modes.
  6607.  
  6608. See also
  6609.  
  6610.    fg_polygonw
  6611.  
  6612. Examples
  6613.  
  6614.    6-7
  6615.  
  6616.  
  6617.  
  6618.  
  6619.  
  6620.  
  6621.  
  6622.  
  6623.  
  6624.  
  6625.  
  6626.  
  6627.  
  6628.  
  6629.  
  6630.  
  6631.  
  6632.  
  6633.                                      108
  6634. fg_polygonw
  6635.  
  6636.  
  6637. Prototype
  6638.  
  6639.    void fg_polygonw (double *x_array, double *y_array, int n);
  6640.  
  6641. Description
  6642.  
  6643.    The fg_polygonw routine draws an unfilled polygon in world space, using two
  6644.    coordinate arrays to define the polygon vertices.  The drawing of the
  6645.    polygon begins at the graphics cursor position, through the vertices
  6646.    defined by the coordinate arrays, and finally back to the original graphics
  6647.    cursor position if necessary.
  6648.  
  6649. Parameters
  6650.  
  6651.    x_array is an arbitrary-length array containing the world space x
  6652.    coordinates of the polygon vertices.
  6653.  
  6654.    y_array is an arbitrary-length array containing the world space y
  6655.    coordinates of the polygon vertices.
  6656.  
  6657.    n is the number of vertices in the polygon.
  6658.  
  6659. Return value
  6660.  
  6661.    none
  6662.  
  6663. Restrictions
  6664.  
  6665.    This routine is not available in Fastgraph/Light and has no effect in text
  6666.    video modes.
  6667.  
  6668. See also
  6669.  
  6670.    fg_polygon
  6671.  
  6672.  
  6673.  
  6674.  
  6675.  
  6676.  
  6677.  
  6678.  
  6679.  
  6680.  
  6681.  
  6682.  
  6683.  
  6684.  
  6685.  
  6686.  
  6687.  
  6688.  
  6689.  
  6690.  
  6691.  
  6692.                                      109
  6693. fg_quiet
  6694.  
  6695.  
  6696. Prototype
  6697.  
  6698.    void fg_quiet (void);
  6699.  
  6700. Description
  6701.  
  6702.    The fg_quiet routine stops continuous synchronous sound started with the
  6703.    fg_sound or fg_voice routines.  It has no effect if there is no continuous
  6704.    sound in progress.
  6705.  
  6706. Parameters
  6707.  
  6708.    none
  6709.  
  6710. Return value
  6711.  
  6712.    none
  6713.  
  6714. Restrictions
  6715.  
  6716.    none
  6717.  
  6718. See also
  6719.  
  6720.    fg_sounds, fg_voices
  6721.  
  6722. Examples
  6723.  
  6724.    13-2
  6725.  
  6726.  
  6727.  
  6728.  
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.  
  6738.  
  6739.  
  6740.  
  6741.  
  6742.  
  6743.  
  6744.  
  6745.  
  6746.  
  6747.  
  6748.  
  6749.  
  6750.  
  6751.                                      110
  6752. fg_rect
  6753.  
  6754.  
  6755. Prototype
  6756.  
  6757.    void fg_rect (int minx, int maxx, int miny, int maxy);
  6758.  
  6759. Description
  6760.  
  6761.    The fg_rect routine draws a solid (filled) rectangle in screen space or
  6762.    character space, without regard to the clipping region.
  6763.  
  6764. Parameters
  6765.  
  6766.    minx is the x coordinate of the rectangle's left edge.
  6767.  
  6768.    maxx is the x coordinate of the rectangle's right edge.  It must be greater
  6769.    than or equal to the value of minx.
  6770.  
  6771.    miny is the y coordinate of the rectangle's top edge.
  6772.  
  6773.    maxy is the y coordinate of the rectangle's bottom edge.  It must be
  6774.    greater than or equal to the value of miny.
  6775.  
  6776. Return value
  6777.  
  6778.    none
  6779.  
  6780. Restrictions
  6781.  
  6782.    none
  6783.  
  6784. See also
  6785.  
  6786.    fg_clprect, fg_clprectw, fg_drect, fg_drectw, fg_rectw
  6787.  
  6788. Examples
  6789.  
  6790.    6-10, 7-4, 7-6
  6791.  
  6792.  
  6793.  
  6794.  
  6795.  
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.  
  6803.  
  6804.  
  6805.  
  6806.  
  6807.  
  6808.  
  6809.  
  6810.                                      111
  6811. fg_rectw
  6812.  
  6813.  
  6814. Prototype
  6815.  
  6816.    void fg_rectw (double xmin, double xmax, double ymin, double ymax);
  6817.  
  6818. Description
  6819.  
  6820.    The fg_rectw routine draws a solid (filled) rectangle in world space,
  6821.    without regard to the clipping region.
  6822.  
  6823. Parameters
  6824.  
  6825.    xmin is the world space x coordinate of the rectangle's left edge.
  6826.  
  6827.    xmax is the world space x coordinate of the rectangle's right edge.  It
  6828.    must be greater than or equal to the value of xmin.
  6829.  
  6830.    ymin is the world space y coordinate of the rectangle's bottom edge.
  6831.  
  6832.    ymax is the world space y coordinate of the rectangle's top edge.  It must
  6833.    be greater than or equal to the value of ymin.
  6834.  
  6835. Return value
  6836.  
  6837.    none
  6838.  
  6839. Restrictions
  6840.  
  6841.    This routine is not available in Fastgraph/Light.
  6842.  
  6843. See also
  6844.  
  6845.    fg_clprect, fg_clprectw, fg_drect, fg_drectw, fg_rect
  6846.  
  6847. Examples
  6848.  
  6849.    7-10
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.                                      112
  6870. fg_reset
  6871.  
  6872.  
  6873. Prototype
  6874.  
  6875.    void fg_reset (void);
  6876.  
  6877. Description
  6878.  
  6879.    When the ANSI.SYS driver is not loaded, the fg_reset routine erases the
  6880.    screen.  When ANSI.SYS is loaded, fg_reset also restores any previously set
  6881.    screen attributes.  It is generally the last Fastgraph routine called in a
  6882.    program.
  6883.  
  6884. Parameters
  6885.  
  6886.    none
  6887.  
  6888. Return value
  6889.  
  6890.    none
  6891.  
  6892. Restrictions
  6893.  
  6894.    This routine has no effect in graphics video modes.
  6895.  
  6896. See also
  6897.  
  6898.    fg_erase
  6899.  
  6900. Examples
  6901.  
  6902.    3-2
  6903.  
  6904.  
  6905.  
  6906.  
  6907.  
  6908.  
  6909.  
  6910.  
  6911.  
  6912.  
  6913.  
  6914.  
  6915.  
  6916.  
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922.  
  6923.  
  6924.  
  6925.  
  6926.  
  6927.  
  6928.                                      113
  6929. fg_restore
  6930.  
  6931.  
  6932. Prototype
  6933.  
  6934.    void fg_restore (int minx, int maxx, int miny, int maxy);
  6935.  
  6936. Description
  6937.  
  6938.    The fg_restore routine copies a rectangular region from the hidden video
  6939.    page to the same position on the active video page.  In text modes, the
  6940.    region is defined in character space; in graphics modes, it is defined in
  6941.    screen space.
  6942.  
  6943. Parameters
  6944.  
  6945.    minx is the x coordinate of the region's left edge.  In graphics modes, its
  6946.    value is reduced to a byte boundary if necessary.
  6947.  
  6948.    maxx is the x coordinate of the region's right edge.  It must be greater
  6949.    than or equal to the value of minx.  In graphics modes, its value is
  6950.    extended to a byte boundary if necessary.
  6951.  
  6952.    miny is the y coordinate of the region's top edge.
  6953.  
  6954.    maxy is the y coordinate of the region's bottom edge.  It must be greater
  6955.    than or equal to the value of miny.
  6956.  
  6957. Return value
  6958.  
  6959.    none
  6960.  
  6961. Restrictions
  6962.  
  6963.    none
  6964.  
  6965. See also
  6966.  
  6967.    fg_restorew, fg_save, fg_savew, fg_sethpage, fg_transfer
  6968.  
  6969. Examples
  6970.  
  6971.    9-21, 9-22
  6972.  
  6973.  
  6974.  
  6975.  
  6976.  
  6977.  
  6978.  
  6979.  
  6980.  
  6981.  
  6982.  
  6983.  
  6984.  
  6985.  
  6986.  
  6987.                                      114
  6988. fg_restorew
  6989.  
  6990.  
  6991. Prototype
  6992.  
  6993.    void fg_restorew (double xmin, double xmax, double ymin, double ymax);
  6994.  
  6995. Description
  6996.  
  6997.    The fg_restorew routine copies a rectangular region, defined in world
  6998.    space, from the hidden video page to the same position on the active video
  6999.    page.
  7000.  
  7001. Parameters
  7002.  
  7003.    xmin is the world space x coordinate of the region's left edge.  In
  7004.    graphics modes, its value is reduced to a byte boundary if necessary.
  7005.  
  7006.    xmax is the world space x coordinate of the region's right edge.  It must
  7007.    be greater than or equal to the value of xmin.  In graphics modes, its
  7008.    value is extended to a byte boundary if necessary.
  7009.  
  7010.    ymin is the world space y coordinate of the region's bottom edge.
  7011.  
  7012.    ymax is the world space y coordinate of the region's top edge.  It must be
  7013.    greater than or equal to the value of ymin.
  7014.  
  7015. Return value
  7016.  
  7017.    none
  7018.  
  7019. Restrictions
  7020.  
  7021.    This routine is not available in Fastgraph/Light.
  7022.  
  7023. See also
  7024.  
  7025.    fg_restore, fg_save, fg_savew, fg_sethpage, fg_transfer
  7026.  
  7027.  
  7028.  
  7029.  
  7030.  
  7031.  
  7032.  
  7033.  
  7034.  
  7035.  
  7036.  
  7037.  
  7038.  
  7039.  
  7040.  
  7041.  
  7042.  
  7043.  
  7044.  
  7045.  
  7046.                                      115
  7047. fg_revimage
  7048.  
  7049.  
  7050. Prototype
  7051.  
  7052.    void fg_revimage (char *map_array, int width, int height);
  7053.  
  7054. Description
  7055.  
  7056.    The fg_revimage routine displays a reversed image stored as a mode-specific
  7057.    bit map.  The image will be positioned so that its lower left corner is at
  7058.    the graphics cursor position.  Refer to the Fastgraph User's Guide for
  7059.    complete information about mode-specific bit maps.
  7060.  
  7061. Parameters
  7062.  
  7063.    map_array is the arbitrary-length array containing the bit map.  For EGA
  7064.    and VGA graphics modes, each color must be in a separate bit map.  For all
  7065.    other graphics modes, all colors are in a single bit map.
  7066.  
  7067.    width is the width in bytes of the bit map.
  7068.  
  7069.    height is the height in bytes (pixel rows) of the bit map.
  7070.  
  7071. Return value
  7072.  
  7073.    none
  7074.  
  7075. Restrictions
  7076.  
  7077.    This routine has no effect in text video modes.
  7078.  
  7079. See also
  7080.  
  7081.    fg_clpimage, fg_drwimage, fg_flpimage, fg_getimage
  7082.  
  7083. Examples
  7084.  
  7085.    9-8, 9-9
  7086.  
  7087.  
  7088.  
  7089.  
  7090.  
  7091.  
  7092.  
  7093.  
  7094.  
  7095.  
  7096.  
  7097.  
  7098.  
  7099.  
  7100.  
  7101.  
  7102.  
  7103.  
  7104.  
  7105.                                      116
  7106. fg_revmask
  7107.  
  7108.  
  7109. Prototype
  7110.  
  7111.    void fg_revmask (char *map_array, int runs, int width);
  7112.  
  7113. Description
  7114.  
  7115.    The fg_revmask routine displays a reversed image stored as a masking map.
  7116.    The image will be positioned so that its lower left corner is at the
  7117.    graphics cursor position.  Refer to the description of the fg_drawmask
  7118.    routine for more information about masking maps.
  7119.  
  7120. Parameters
  7121.  
  7122.    map_array is the arbitrary-length array containing the masking map.
  7123.  
  7124.    runs is the number of pixel runs in the masking map.
  7125.  
  7126.    width is the width in pixels of the masking map.
  7127.  
  7128. Return value
  7129.  
  7130.    none
  7131.  
  7132. Restrictions
  7133.  
  7134.    This routine has no effect in text video modes, or in the native EGA and
  7135.    VGA graphics video modes.
  7136.  
  7137. See also
  7138.  
  7139.    fg_clipmask, fg_drawmask, fg_flipmask
  7140.  
  7141. Examples
  7142.  
  7143.    9-15
  7144.  
  7145.  
  7146.  
  7147.  
  7148.  
  7149.  
  7150.  
  7151.  
  7152.  
  7153.  
  7154.  
  7155.  
  7156.  
  7157.  
  7158.  
  7159.  
  7160.  
  7161.  
  7162.                                      117
  7163. fg_save
  7164.  
  7165.  
  7166. Prototype
  7167.  
  7168.    void fg_save (int minx, int maxx, int miny, int maxy);
  7169.  
  7170. Description
  7171.  
  7172.    The fg_save routine copies a rectangular region from the active video page
  7173.    to the same position on the hidden video page.  In text modes, the region
  7174.    is defined in character space; in graphics modes, it is defined in screen
  7175.    space.
  7176.  
  7177. Parameters
  7178.  
  7179.    minx is the x coordinate of the region's left edge.  In graphics modes, its
  7180.    value is reduced to a byte boundary if necessary.
  7181.  
  7182.    maxx is the x coordinate of the region's right edge.  It must be greater
  7183.    than or equal to the value of minx.  In graphics modes, its value is
  7184.    extended to a byte boundary if necessary.
  7185.  
  7186.    miny is the y coordinate of the region's top edge.
  7187.  
  7188.    maxy is the y coordinate of the region's bottom edge.  It must be greater
  7189.    than or equal to the value of miny.
  7190.  
  7191. Return value
  7192.  
  7193.    none
  7194.  
  7195. Restrictions
  7196.  
  7197.    none
  7198.  
  7199. See also
  7200.  
  7201.    fg_restore, fg_restorew, fg_savew, fg_sethpage, fg_transfer
  7202.  
  7203. Examples
  7204.  
  7205.    9-21, 9-22
  7206.  
  7207.  
  7208.  
  7209.  
  7210.  
  7211.  
  7212.  
  7213.  
  7214.  
  7215.  
  7216.  
  7217.  
  7218.  
  7219.  
  7220.  
  7221.  
  7222.  
  7223.                                      118
  7224. fg_savew
  7225.  
  7226.  
  7227. Prototype
  7228.  
  7229.    void fg_savew (double xmin, double xmax, double ymin, double ymax);
  7230.  
  7231. Description
  7232.  
  7233.    The fg_savew routine copies a rectangular region, defined in world space,
  7234.    from the active video page to the same position on the hidden video page.
  7235.  
  7236. Parameters
  7237.  
  7238.    xmin is the world space x coordinate of the region's left edge.  In
  7239.    graphics modes, its value is reduced to a byte boundary if necessary.
  7240.  
  7241.    xmax is the world space x coordinate of the region's right edge.  It must
  7242.    be greater than or equal to the value of xmin.  In graphics modes, its
  7243.    value is extended to a byte boundary if necessary.
  7244.  
  7245.    ymin is the world space y coordinate of the region's bottom edge.
  7246.  
  7247.    ymax is the world space y coordinate of the region's top edge.  It must be
  7248.    greater than or equal to the value of ymin.
  7249.  
  7250. Return value
  7251.  
  7252.    none
  7253.  
  7254. Restrictions
  7255.  
  7256.    This routine is not available in Fastgraph/Light.
  7257.  
  7258. See also
  7259.  
  7260.    fg_restore, fg_restorew, fg_save, fg_sethpage, fg_transfer
  7261.  
  7262.  
  7263.  
  7264.  
  7265.  
  7266.  
  7267.  
  7268.  
  7269.  
  7270.  
  7271.  
  7272.  
  7273.  
  7274.  
  7275.  
  7276.  
  7277.  
  7278.  
  7279.  
  7280.  
  7281.  
  7282.                                      119
  7283. fg_scrlock
  7284.  
  7285.  
  7286. Prototype
  7287.  
  7288.    int fg_scrlock (void);
  7289.  
  7290. Description
  7291.  
  7292.    The fg_scrlock routine determines the state of the ScrollLock key.
  7293.  
  7294. Parameters
  7295.  
  7296.    none
  7297.  
  7298. Return value
  7299.  
  7300.    If the return value is 0, it means the ScrollLock key is off.  If it is 1,
  7301.    it means the ScrollLock key is on.
  7302.  
  7303. Restrictions
  7304.  
  7305.    Not all PC keyboards have a ScrollLock key.  For such systems, fg_scrlock
  7306.    will return a value of zero.
  7307.  
  7308. See also
  7309.  
  7310.    fg_capslock, fg_numlock, fg_setcaps, fg_setnum
  7311.  
  7312. Examples
  7313.  
  7314.    12-3
  7315.  
  7316.  
  7317.  
  7318.  
  7319.  
  7320.  
  7321.  
  7322.  
  7323.  
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.  
  7331.  
  7332.  
  7333.  
  7334.  
  7335.  
  7336.  
  7337.  
  7338.  
  7339.  
  7340.  
  7341.                                      120
  7342. fg_scroll
  7343.  
  7344.  
  7345. Prototype
  7346.  
  7347.    void fg_scroll (int minx, int maxx, int miny, int maxy, int jump, int
  7348.    type);
  7349.  
  7350. Description
  7351.  
  7352.    The fg_scroll routine vertically scrolls a region of the active video page.
  7353.    The scrolling may be done either up or down, using either an end-off or
  7354.    circular method.  In text modes, the region is defined in character space;
  7355.    in graphics modes, it is defined in screen space.
  7356.  
  7357. Parameters
  7358.  
  7359.    minx is the x coordinate of the scrolling region's left edge.  In graphics
  7360.    modes, its value is reduced to a byte boundary if necessary.
  7361.  
  7362.    maxx is the x coordinate of the scrolling region's right edge.  It must be
  7363.    greater than or equal to the value of minx.  In graphics modes, its value
  7364.    is extended to a byte boundary if necessary.
  7365.  
  7366.    miny is the y coordinate of the scrolling region's top edge.
  7367.  
  7368.    maxy is the y coordinate of the scrolling region's bottom edge.  It must be
  7369.    greater than or equal to the value of miny.
  7370.  
  7371.    jump is the number of pixels to jump between each scrolling iteration.  If
  7372.    jump is negative, the region will scroll toward the top of the screen.  If
  7373.    jump is positive, the region will scroll toward the bottom of the screen.
  7374.  
  7375.    type specifies the type of scroll.  If type is zero, rows that scroll off
  7376.    one edge appear at the opposite edge, thus producing a circular scrolling
  7377.    effect.  If type is any other value, rows that scroll off one edge will be
  7378.    replaced at the opposite edge by lines of the current color.
  7379.  
  7380. Return value
  7381.  
  7382.    none
  7383.  
  7384. Restrictions
  7385.  
  7386.    Circular scrolling uses part of the hidden page (as defined in the most
  7387.    recent call to fg_sethpage) as a temporary workspace.
  7388.  
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.  
  7397.  
  7398.  
  7399.  
  7400.                                      121
  7401. fg_scroll (continued)
  7402.  
  7403.  
  7404. See also
  7405.  
  7406.    fg_setcolor, fg_sethpage
  7407.  
  7408. Examples
  7409.  
  7410.    11-3, 11-4, 11-5
  7411.  
  7412.  
  7413.  
  7414.  
  7415.  
  7416.  
  7417.  
  7418.  
  7419.  
  7420.  
  7421.  
  7422.  
  7423.  
  7424.  
  7425.  
  7426.  
  7427.  
  7428.  
  7429.  
  7430.  
  7431.  
  7432.  
  7433.  
  7434.  
  7435.  
  7436.  
  7437.  
  7438.  
  7439.  
  7440.  
  7441.  
  7442.  
  7443.  
  7444.  
  7445.  
  7446.  
  7447.  
  7448.  
  7449.  
  7450.  
  7451.  
  7452.  
  7453.  
  7454.  
  7455.  
  7456.  
  7457.  
  7458.  
  7459.                                      122
  7460. fg_setangle
  7461.  
  7462.  
  7463. Prototype
  7464.  
  7465.    void fg_setangle (double angle);
  7466.  
  7467. Description
  7468.  
  7469.    The fg_setangle routine defines the angle or orientation at which software
  7470.    characters are displayed.  If a program draws software characters before
  7471.    calling fg_setangle, Fastgraph will use its default angle of zero degrees
  7472.    (that is, horizontal).
  7473.  
  7474. Parameters
  7475.  
  7476.    angle is the angle of rotation, expressed in degrees and measured
  7477.    counterclockwise from the positive x axis.
  7478.  
  7479. Return value
  7480.  
  7481.    none
  7482.  
  7483. Restrictions
  7484.  
  7485.    This routine is not available in Fastgraph/Light.  Before using this
  7486.    routine, you must use the fg_initw and fg_setworld routines to establish a
  7487.    world space coordinate system.
  7488.  
  7489. See also
  7490.  
  7491.    fg_initw, fg_setratio, fg_setsize, fg_setsizew, fg_setworld, fg_swchar,
  7492.    fg_swlength, fg_swtext
  7493.  
  7494. Examples
  7495.  
  7496.    7-9
  7497.  
  7498.  
  7499.  
  7500.  
  7501.  
  7502.  
  7503.  
  7504.  
  7505.  
  7506.  
  7507.  
  7508.  
  7509.  
  7510.  
  7511.  
  7512.  
  7513.  
  7514.  
  7515.  
  7516.  
  7517.  
  7518.                                      123
  7519. fg_setattr
  7520.  
  7521.  
  7522. Prototype
  7523.  
  7524.    void fg_setattr (int foreground, int background, int blink);
  7525.  
  7526. Description
  7527.  
  7528.    The fg_setattr routine establishes the current text attribute in text video
  7529.    modes.
  7530.  
  7531. Parameters
  7532.  
  7533.    foreground is attribute's foreground component, between 0 and 15.
  7534.  
  7535.    background is the attribute's background component, between 0 and 7.
  7536.  
  7537.    blink is the attribute's blink component, between 0 and 1.
  7538.  
  7539. Return value
  7540.  
  7541.    none
  7542.  
  7543. Restrictions
  7544.  
  7545.    This routine has no effect in graphics video modes.
  7546.  
  7547. See also
  7548.  
  7549.    fg_setcolor
  7550.  
  7551. Examples
  7552.  
  7553.    7-1, 7-2, 7-3, 8-1, 8-3, 8-5, 8-7, 9-20, 9-21, 9-23, 11-4, 12-8
  7554.  
  7555.  
  7556.  
  7557.  
  7558.  
  7559.  
  7560.  
  7561.  
  7562.  
  7563.  
  7564.  
  7565.  
  7566.  
  7567.  
  7568.  
  7569.  
  7570.  
  7571.  
  7572.  
  7573.  
  7574.  
  7575.  
  7576.  
  7577.                                      124
  7578. fg_setcaps
  7579.  
  7580.  
  7581. Prototype
  7582.  
  7583.    void fg_setcaps (int state);
  7584.  
  7585. Description
  7586.  
  7587.    The fg_setcaps routine controls the state of the CapsLock key.
  7588.  
  7589. Parameters
  7590.  
  7591.    state defines the CapsLock key state.  If state is 0, the CapsLock key is
  7592.    turned off.  If it is 1, the CapsLock key is turned on.
  7593.  
  7594. Return value
  7595.  
  7596.    none
  7597.  
  7598. Restrictions
  7599.  
  7600.    On most keyboards, changing the CapsLock key state will also change the
  7601.    keyboard state light to reflect the new key state.  However, some older
  7602.    keyboards, especially when used on PC, PC/XT, or Tandy 1000 systems, do not
  7603.    update the state light.  This makes the state light inconsistent with the
  7604.    true key state.
  7605.  
  7606. See also
  7607.  
  7608.    fg_capslock, fg_numlock, fg_scrlock, fg_setnum
  7609.  
  7610. Examples
  7611.  
  7612.    12-4
  7613.  
  7614.  
  7615.  
  7616.  
  7617.  
  7618.  
  7619.  
  7620.  
  7621.  
  7622.  
  7623.  
  7624.  
  7625.  
  7626.  
  7627.  
  7628.  
  7629.  
  7630.  
  7631.  
  7632.  
  7633.  
  7634.  
  7635.  
  7636.                                      125
  7637. fg_setclip
  7638.  
  7639.  
  7640. Prototype
  7641.  
  7642.    void fg_setclip (int minx, int maxx, int miny, int maxy);
  7643.  
  7644. Description
  7645.  
  7646.    The fg_setclip routine defines the clipping region in screen space.  The
  7647.    clipping region is a rectangular area outside of which graphics are
  7648.    suppressed.
  7649.  
  7650. Parameters
  7651.  
  7652.    minx is the screen space x coordinate of the clipping region's left edge.
  7653.  
  7654.    maxx is the screen space x coordinate of the clipping region's right edge.
  7655.    It must be greater than or equal to the value of minx.
  7656.  
  7657.    miny is the screen space y coordinate of the clipping region's top edge.
  7658.  
  7659.    maxy is the screen space y coordinate of the clipping region's bottom edge.
  7660.    It must be greater than or equal to the value of miny.
  7661.  
  7662. Return value
  7663.  
  7664.    none
  7665.  
  7666. Restrictions
  7667.  
  7668.    This routine has no effect in text video modes.
  7669.  
  7670. See also
  7671.  
  7672.    fg_setclipw
  7673.  
  7674. Examples
  7675.  
  7676.    6-5, 9-8, 9-9, 9-15, 10-4
  7677.  
  7678.  
  7679.  
  7680.  
  7681.  
  7682.  
  7683.  
  7684.  
  7685.  
  7686.  
  7687.  
  7688.  
  7689.  
  7690.  
  7691.  
  7692.  
  7693.  
  7694.  
  7695.                                      126
  7696. fg_setclipw
  7697.  
  7698.  
  7699. Prototype
  7700.  
  7701.    void fg_setclipw (double xmin, double xmax, double ymin, double ymax);
  7702.  
  7703. Description
  7704.  
  7705.    The fg_setclipw routine defines the clipping region in world space.  The
  7706.    clipping region is a rectangular area outside of which graphics are
  7707.    suppressed.
  7708.  
  7709. Parameters
  7710.  
  7711.    xmin is the world space x coordinate of the clipping region's left edge.
  7712.  
  7713.    xmax is the world space x coordinate of the clipping region's right edge.
  7714.    It must be greater than or equal to the value of xmin.
  7715.  
  7716.    ymin is the world space y coordinate of the clipping region's bottom edge.
  7717.  
  7718.    ymax is the world space y coordinate of the clipping region's top edge.  It
  7719.    must be greater than or equal to the value of ymin.
  7720.  
  7721. Return value
  7722.  
  7723.    none
  7724.  
  7725. Restrictions
  7726.  
  7727.    This routine is not available in Fastgraph/Light and has no effect in text
  7728.    video modes.
  7729.  
  7730. See also
  7731.  
  7732.    fg_setclip
  7733.  
  7734.  
  7735.  
  7736.  
  7737.  
  7738.  
  7739.  
  7740.  
  7741.  
  7742.  
  7743.  
  7744.  
  7745.  
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.  
  7752.  
  7753.  
  7754.                                      127
  7755. fg_setcolor
  7756.  
  7757.  
  7758. Prototype
  7759.  
  7760.    void fg_setcolor (int color);
  7761.  
  7762. Description
  7763.  
  7764.    The fg_setcolor routine establishes the current color index (which may be a
  7765.    virtual color index) in graphics modes.  In text modes, fg_setcolor
  7766.    provides an alternate method of defining the current text attribute.
  7767.  
  7768. Parameters
  7769.  
  7770.    color defines the current color index (in graphics modes) or text attribute
  7771.    (in text modes).  Its value must be between 0 and 255.
  7772.  
  7773. Return value
  7774.  
  7775.    none
  7776.  
  7777. Restrictions
  7778.  
  7779.    none
  7780.  
  7781. See also
  7782.  
  7783.    fg_defcolor, fg_getcolor, fg_palette
  7784.  
  7785. Examples
  7786.  
  7787.    3-1 to 3-8
  7788.  
  7789.  
  7790.  
  7791.  
  7792.  
  7793.  
  7794.  
  7795.  
  7796.  
  7797.  
  7798.  
  7799.  
  7800.  
  7801.  
  7802.  
  7803.  
  7804.  
  7805.  
  7806.  
  7807.  
  7808.  
  7809.  
  7810.  
  7811.  
  7812.  
  7813.                                      128
  7814. fg_setfunc
  7815.  
  7816.  
  7817. Prototype
  7818.  
  7819.    void fg_setfunc (int mode);
  7820.  
  7821. Description
  7822.  
  7823.    The fg_setfunc routine specifies the logical operation applied when video
  7824.    memory changes in the native EGA and VGA graphics modes.  Replacement mode
  7825.    is selected after you use the fg_setmode routine to establish a video mode.
  7826.  
  7827. Parameters
  7828.  
  7829.    mode defines the logical operation, as shown below.
  7830.  
  7831.  
  7832.                     value of   logical
  7833.                       mode    operation
  7834.  
  7835.                         0     replacement
  7836.                         1     and
  7837.                         2     or
  7838.                         3     exclusive or
  7839.  
  7840.  
  7841.  
  7842. Return value
  7843.  
  7844.    none
  7845.  
  7846. Restrictions
  7847.  
  7848.    This routine only functions in the native EGA and VGA graphics video modes
  7849.    (modes 13 through 18).
  7850.  
  7851. Examples
  7852.  
  7853.    10-3, 15-2
  7854.  
  7855.  
  7856.  
  7857.  
  7858.  
  7859.  
  7860.  
  7861.  
  7862.  
  7863.  
  7864.  
  7865.  
  7866.  
  7867.  
  7868.  
  7869.  
  7870.  
  7871.  
  7872.                                      129
  7873. fg_sethpage
  7874.  
  7875.  
  7876. Prototype
  7877.  
  7878.    void fg_sethpage (int page_number);
  7879.  
  7880. Description
  7881.  
  7882.    The fg_sethpage routine establishes the hidden video page.  It may be a
  7883.    physical or virtual video page.  The fg_setmode routine designates video
  7884.    page 0 as the hidden page.
  7885.  
  7886. Parameters
  7887.  
  7888.    page_number is the hidden video page number, between 0 and 15.
  7889.  
  7890. Return value
  7891.  
  7892.    none
  7893.  
  7894. Restrictions
  7895.  
  7896.    This routine has no effect if page_number references a physical video page
  7897.    that does not exist, or a virtual video page that has not been created.
  7898.  
  7899. See also
  7900.  
  7901.    fg_gethpage, fg_setpage, fg_setvpage
  7902.  
  7903. Examples
  7904.  
  7905.    9-21, 9-22, 11-2, 11-5
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.  
  7915.  
  7916.  
  7917.  
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.  
  7925.  
  7926.  
  7927.  
  7928.  
  7929.  
  7930.  
  7931.                                      130
  7932. fg_setmode
  7933.  
  7934.  
  7935. Prototype
  7936.  
  7937.    void fg_setmode (int mode);
  7938.  
  7939. Description
  7940.  
  7941.    The fg_setmode routine establishes a video mode and initializes Fastgraph's
  7942.    internal parameters for that video mode.  It must be called before any
  7943.    Fastgraph routine that performs video output.  A program can call
  7944.    fg_setmode as many times as needed to switch between different video modes.
  7945.  
  7946. Parameters
  7947.  
  7948.    mode is the video mode number, between 0 and 21.  The following table lists
  7949.    Fastgraph's supported video modes.
  7950.  
  7951.  
  7952.     Mode                       No. of     Supported          Supported
  7953.    Number  Type    Resolution  Colors     Adapters           Displays
  7954.  
  7955.       0    Text    40 x 25     16/8       CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7956.       1    Text    40 x 25     16/8       CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7957.       2    Text    80 x 25     16/8       CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7958.       3    Text    80 x 25     16/8       CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7959.       4  Graphics  320 x 200   4          CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7960.       5  Graphics  320 x 200   4          CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7961.       6  Graphics  640 x 200   2/16       CGA,EGA,VGA,MCGA   RGB,ECD,VGA
  7962.       7    Text    80 x 25     b/w        MDA,HGC,EGA,VGA    Mono,ECD,VGA
  7963.       9  Graphics  320 x 200   16         Tandy 1000,PCjr    RGB
  7964.      11  Graphics  720 x 348   b/w        HGC                Monochrome
  7965.      12  Graphics  320 x 200   b/w        HGC                Monochrome
  7966.      13  Graphics  320 x 200   16         EGA,VGA            RGB,ECD,VGA
  7967.      14  Graphics  640 x 200   16         EGA,VGA            RGB,ECD,VGA
  7968.      15  Graphics  640 x 350   b/w        EGA,VGA            Monochrome,VGA
  7969.      16  Graphics  640 x 350   16/64      EGA,VGA            ECD,VGA
  7970.      17  Graphics  640 x 480   2/256K     VGA,MCGA           VGA
  7971.      18  Graphics  640 x 480   16/256K    VGA                VGA
  7972.      19  Graphics  320 x 200   256/256K   VGA,MCGA           VGA
  7973.      20  Graphics  320 x 200   256/256K   VGA                VGA
  7974.      21  Graphics  320 x 400   256/256K   VGA                VGA
  7975.  
  7976.  
  7977.    For more information about each video mode, including their required
  7978.    display adapters (graphics cards) and monitors, please refer to the
  7979.    Fastgraph User's Guide.
  7980.  
  7981.    The value of the mode parameter can also be -1, which tells Fastgraph to
  7982.    use the current video mode.  This feature is often useful in programs that
  7983.    use only text video modes, programs executed from another program, or
  7984.    terminate and stay resident (TSR) programs.
  7985.  
  7986.  
  7987.  
  7988.  
  7989.  
  7990.                                      131
  7991. fg_setmode (continued)
  7992.  
  7993.  
  7994. Return value
  7995.  
  7996.    none
  7997.  
  7998. Restrictions
  7999.  
  8000.    The fg_setmode routine does not check if the specified video mode is
  8001.    available on the user's system.  If necessary, you should first use the
  8002.    fg_testmode routine to do this.
  8003.  
  8004. See also
  8005.  
  8006.    fg_automode, fg_bestmode, fg_testmode
  8007.  
  8008. Examples
  8009.  
  8010.    3-1
  8011.  
  8012.  
  8013.  
  8014.  
  8015.  
  8016.  
  8017.  
  8018.  
  8019.  
  8020.  
  8021.  
  8022.  
  8023.  
  8024.  
  8025.  
  8026.  
  8027.  
  8028.  
  8029.  
  8030.  
  8031.  
  8032.  
  8033.  
  8034.  
  8035.  
  8036.  
  8037.  
  8038.  
  8039.  
  8040.  
  8041.  
  8042.  
  8043.  
  8044.  
  8045.  
  8046.  
  8047.  
  8048.  
  8049.                                      132
  8050. fg_setnum
  8051.  
  8052.  
  8053. Prototype
  8054.  
  8055.    void fg_setnum (int state);
  8056.  
  8057. Description
  8058.  
  8059.    The fg_setnum routine controls the state of the NumLock key.
  8060.  
  8061. Parameters
  8062.  
  8063.    state defines the NumLock key state.  If state is 0, the NumLock key is
  8064.    turned off.  If it is 1, the NumLock key is turned on.
  8065.  
  8066. Return value
  8067.  
  8068.    none
  8069.  
  8070. Restrictions
  8071.  
  8072.    On most keyboards, changing the NumLock key state will also change the
  8073.    keyboard state light to reflect the new key state.  However, some older
  8074.    keyboards, especially when used on PC, PC/XT, or Tandy 1000 systems, do not
  8075.    update the state light.  This makes the state light inconsistent with the
  8076.    true key state.
  8077.  
  8078. See also
  8079.  
  8080.    fg_capslock, fg_numlock, fg_scrlock, fg_setcaps
  8081.  
  8082. Examples
  8083.  
  8084.    12-4
  8085.  
  8086.  
  8087.  
  8088.  
  8089.  
  8090.  
  8091.  
  8092.  
  8093.  
  8094.  
  8095.  
  8096.  
  8097.  
  8098.  
  8099.  
  8100.  
  8101.  
  8102.  
  8103.  
  8104.  
  8105.  
  8106.  
  8107.  
  8108.                                      133
  8109. fg_setpage
  8110.  
  8111.  
  8112. Prototype
  8113.  
  8114.    void fg_setpage (int page_number);
  8115.  
  8116. Description
  8117.  
  8118.    The fg_setpage routine establishes the active video page.  It may be a
  8119.    physical or virtual video page.  The fg_setmode routine designates video
  8120.    page 0 as the active page.
  8121.  
  8122. Parameters
  8123.  
  8124.    page_number is the active video page number, between 0 and 15.
  8125.  
  8126. Return value
  8127.  
  8128.    none
  8129.  
  8130. Restrictions
  8131.  
  8132.    This routine has no effect if page_number references a physical video page
  8133.    that does not exist, or a virtual video page that has not been created.
  8134.  
  8135. See also
  8136.  
  8137.    fg_getpage, fg_sethpage, fg_setvpage
  8138.  
  8139. Examples
  8140.  
  8141.    8-1 to 8-8, 10-4, 10-5, 11-2
  8142.  
  8143.  
  8144.  
  8145.  
  8146.  
  8147.  
  8148.  
  8149.  
  8150.  
  8151.  
  8152.  
  8153.  
  8154.  
  8155.  
  8156.  
  8157.  
  8158.  
  8159.  
  8160.  
  8161.  
  8162.  
  8163.  
  8164.  
  8165.  
  8166.  
  8167.                                      134
  8168. fg_setratio
  8169.  
  8170.  
  8171. Prototype
  8172.  
  8173.    void fg_setratio (double ratio);
  8174.  
  8175. Description
  8176.  
  8177.    The fg_setratio routine defines the aspect ratio for software characters.
  8178.    The aspect ratio is the ratio of character width to character height.  If a
  8179.    program draws software characters before calling fg_setratio, Fastgraph
  8180.    will use its default aspect ratio of 1.
  8181.  
  8182. Parameters
  8183.  
  8184.    ratio is the aspect ratio.  It must be greater than zero.
  8185.  
  8186. Return value
  8187.  
  8188.    none
  8189.  
  8190. Restrictions
  8191.  
  8192.    This routine is not available in Fastgraph/Light.  Before using this
  8193.    routine, you must use the fg_initw and fg_setworld routines to establish a
  8194.    world space coordinate system.
  8195.  
  8196. See also
  8197.  
  8198.    fg_initw, fg_setangle, fg_setsize, fg_setsizew, fg_setworld, fg_swchar,
  8199.    fg_swlength, fg_swtext
  8200.  
  8201. Examples
  8202.  
  8203.    7-8
  8204.  
  8205.  
  8206.  
  8207.  
  8208.  
  8209.  
  8210.  
  8211.  
  8212.  
  8213.  
  8214.  
  8215.  
  8216.  
  8217.  
  8218.  
  8219.  
  8220.  
  8221.  
  8222.  
  8223.  
  8224.  
  8225.  
  8226.                                      135
  8227. fg_setrgb
  8228.  
  8229.  
  8230. Prototype
  8231.  
  8232.    void fg_setrgb (int number, int red, int green, int blue);
  8233.  
  8234. Description
  8235.  
  8236.    The fg_setrgb defines the value of a palette register (in Tandy/PCjr and
  8237.    EGA graphics modes) or video DAC register (in VGA and MCGA graphics modes)
  8238.    by specifying its red, green, and blue color components.
  8239.  
  8240. Parameters
  8241.  
  8242.    number is the palette or video DAC register number.  If it references a
  8243.    palette register, it must be between 0 and 15 (0 and 1 in mode 17).  If it
  8244.    references a video DAC register, it must be between 0 and 255.  The value
  8245.    of number may be negative to specify an intense color for that palette
  8246.    register in Tandy/PCjr and 200-line EGA graphics modes.
  8247.  
  8248.    red, green, and blue respectively specify the red, green, and blue
  8249.    components of the specified palette or video DAC register.  These values
  8250.    must be 0 or 1 for Tandy/PCjr and 200-line EGA graphics modes, between 0
  8251.    and 3 for 350-line EGA modes, and between 0 and 63 for VGA and MCGA modes.
  8252.  
  8253. Return value
  8254.  
  8255.    none
  8256.  
  8257. Restrictions
  8258.  
  8259.    This routine has no effect in text video modes, CGA graphics modes, or
  8260.    Hercules graphics modes.
  8261.  
  8262. See also
  8263.  
  8264.    fg_getrgb, fg_palette, fg_setcolor
  8265.  
  8266. Examples
  8267.  
  8268.    5-9, 5-11, 5-14, 9-14
  8269.  
  8270.  
  8271.  
  8272.  
  8273.  
  8274.  
  8275.  
  8276.  
  8277.  
  8278.  
  8279.  
  8280.  
  8281.  
  8282.  
  8283.  
  8284.  
  8285.                                      136
  8286. fg_setsize
  8287.  
  8288.  
  8289. Prototype
  8290.  
  8291.    void fg_setsize (int isize);
  8292.  
  8293. Description
  8294.  
  8295.    The fg_setsize routine defines the height of software characters in screen
  8296.    space units.  If neither fg_setsize nor fg_setsizew is called, Fastgraph
  8297.    will use its default character height of one world space unit.
  8298.  
  8299. Parameters
  8300.  
  8301.    isize is the character height in screen space units.
  8302.  
  8303. Return value
  8304.  
  8305.    none
  8306.  
  8307. Restrictions
  8308.  
  8309.    This routine is not available in Fastgraph/Light.  Before using this
  8310.    routine, you must use the fg_initw and fg_setworld routines to establish a
  8311.    world space coordinate system.
  8312.  
  8313. See also
  8314.  
  8315.    fg_initw, fg_setangle, fg_setratio, fg_setsizew, fg_setworld, fg_swchar,
  8316.    fg_swlength, fg_swtext
  8317.  
  8318.  
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324.  
  8325.  
  8326.  
  8327.  
  8328.  
  8329.  
  8330.  
  8331.  
  8332.  
  8333.  
  8334.  
  8335.  
  8336.  
  8337.  
  8338.  
  8339.  
  8340.  
  8341.  
  8342.  
  8343.  
  8344.                                      137
  8345. fg_setsizew
  8346.  
  8347.  
  8348. Prototype
  8349.  
  8350.    void fg_setsizew (double size);
  8351.  
  8352. Description
  8353.  
  8354.    The fg_setsizew routine defines the height of software characters in world
  8355.    space units.  If neither fg_setsize nor fg_setsizew is called, Fastgraph
  8356.    will use its default character height of one world space unit.
  8357.  
  8358. Parameters
  8359.  
  8360.    size is the character height in world space units.
  8361.  
  8362. Return value
  8363.  
  8364.    none
  8365.  
  8366. Restrictions
  8367.  
  8368.    This routine is not available in Fastgraph/Light.  Before using this
  8369.    routine, you must use the fg_initw and fg_setworld routines to establish a
  8370.    world space coordinate system.
  8371.  
  8372. See also
  8373.  
  8374.    fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setworld, fg_swchar,
  8375.    fg_swlength, fg_swtext
  8376.  
  8377. Examples
  8378.  
  8379.    7-7, 7-8, 7-9, 7-10
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.  
  8387.  
  8388.  
  8389.  
  8390.  
  8391.  
  8392.  
  8393.  
  8394.  
  8395.  
  8396.  
  8397.  
  8398.  
  8399.  
  8400.  
  8401.  
  8402.  
  8403.                                      138
  8404. fg_setvpage
  8405.  
  8406.  
  8407. Prototype
  8408.  
  8409.    void fg_setvpage (int page_number);
  8410.  
  8411. Description
  8412.  
  8413.    The fg_setvpage routine establishes the visual video page.  It may be a
  8414.    physical or virtual video page.  The fg_setmode routine designates video
  8415.    page 0 as the visual page.
  8416.  
  8417. Parameters
  8418.  
  8419.    page_number is the visual video page number, between 0 and 15.
  8420.  
  8421. Return value
  8422.  
  8423.    none
  8424.  
  8425. Restrictions
  8426.  
  8427.    This routine has no effect if page_number references a physical video page
  8428.    that does not exist, or a virtual video page that has not been created.
  8429.  
  8430. See also
  8431.  
  8432.    fg_getpage, fg_sethpage, fg_setpage
  8433.  
  8434. Examples
  8435.  
  8436.    8-1 to 8-7
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442.  
  8443.  
  8444.  
  8445.  
  8446.  
  8447.  
  8448.  
  8449.  
  8450.  
  8451.  
  8452.  
  8453.  
  8454.  
  8455.  
  8456.  
  8457.  
  8458.  
  8459.  
  8460.  
  8461.  
  8462.                                      139
  8463. fg_setworld
  8464.  
  8465.  
  8466. Prototype
  8467.  
  8468.    void fg_setworld (double xmin, double xmax, double ymin, double ymax);
  8469.  
  8470. Description
  8471.  
  8472.    The fg_setworld routine defines the world space coordinates that correspond
  8473.    to the physical edges of the screen.
  8474.  
  8475. Parameters
  8476.  
  8477.    xmin is the world space coordinate of the screen's left edge.
  8478.  
  8479.    xmax is the world space coordinate of the screen's right edge.  It must be
  8480.    greater than the value of xmin.
  8481.  
  8482.    ymin is the world space coordinate of the screen's top edge.
  8483.  
  8484.    ymax is the world space coordinate of the screen's bottom edge.  It must be
  8485.    greater than the value of ymin.
  8486.  
  8487. Return value
  8488.  
  8489.    none
  8490.  
  8491. Restrictions
  8492.  
  8493.    This routine is not available in Fastgraph/Light.  Before using this
  8494.    routine, you must call the fg_initw routine to initialize Fastgraph's world
  8495.    space parameters.
  8496.  
  8497. See also
  8498.  
  8499.    fg_getworld, fg_initw
  8500.  
  8501. Examples
  8502.  
  8503.    4-3, 6-4, 6-8, 7-7, 7-8, 7-9, 7-10
  8504.  
  8505.  
  8506.  
  8507.  
  8508.  
  8509.  
  8510.  
  8511.  
  8512.  
  8513.  
  8514.  
  8515.  
  8516.  
  8517.  
  8518.  
  8519.  
  8520.  
  8521.                                      140
  8522. fg_sound
  8523.  
  8524.  
  8525. Prototype
  8526.  
  8527.    void fg_sound (int frequency, int duration);
  8528.  
  8529. Description
  8530.  
  8531.    The fg_sound routine produces a tone of a specified frequency and duration
  8532.    using the programmable timer.
  8533.  
  8534. Parameters
  8535.  
  8536.    frequency is tone's frequency in Hertz, between 18 and 32,767.
  8537.  
  8538.    duration is the tone's length in clock ticks (there are approximately 18.2
  8539.    clock ticks per second).  If duration is zero or negative, the tone is said
  8540.    to be continuous and will play until you stop it with the fg_quiet routine.
  8541.  
  8542. Return value
  8543.  
  8544.    none
  8545.  
  8546. Restrictions
  8547.  
  8548.    This routine has no effect if there is asynchronous sound already in
  8549.    progress.
  8550.  
  8551. See also
  8552.  
  8553.    fg_music, fg_quiet, fg_sounds, fg_voice
  8554.  
  8555. Examples
  8556.  
  8557.    13-1
  8558.  
  8559.  
  8560.  
  8561.  
  8562.  
  8563.  
  8564.  
  8565.  
  8566.  
  8567.  
  8568.  
  8569.  
  8570.  
  8571.  
  8572.  
  8573.  
  8574.  
  8575.  
  8576.  
  8577.  
  8578.  
  8579.  
  8580.                                      141
  8581. fg_sounds
  8582.  
  8583.  
  8584. Prototype
  8585.  
  8586.    void fg_sounds (int *sound_array, int ntimes);
  8587.  
  8588. Description
  8589.  
  8590.    The fg_sounds routine uses the programmable timer to play a series of tones
  8591.    of specified frequencies and durations, concurrent with other activity.  It
  8592.    is the asynchronous version of the fg_sound routine.
  8593.  
  8594. Parameters
  8595.  
  8596.    sound_array is an arbitrary-length array containing a series of
  8597.    (frequency,duration) sound definitions.  The format of this array is:
  8598.  
  8599.  
  8600.                           [0]    frequency of sound 1
  8601.  
  8602.                           [1]    duration  of sound 1
  8603.  
  8604.                           [2]    frequency of sound 2
  8605.  
  8606.                           [3]    duration  of sound 2
  8607.                            .
  8608.                            .
  8609.                            .
  8610.  
  8611.                        [2n-2]    frequency of sound n
  8612.  
  8613.                        [2n-1]    duration  of sound n
  8614.  
  8615.                          [2n]       terminator (0)
  8616.  
  8617.  
  8618.    Each frequency value is measured in Hertz and must be between 18 and
  8619.    32,767.  The durations are measured in clock ticks (there are approximately
  8620.    72.8 clock ticks per second).  A null character (that is, a zero byte)
  8621.    terminates the array.
  8622.  
  8623.    ntimes specifies the number of times to cycle through the sounds defined in
  8624.    sound_array.  If ntimes is negative, the sounds will play repetitively
  8625.    until stopped with the fg_hush or fg_hushnext routine.
  8626.  
  8627. Return value
  8628.  
  8629.    none
  8630.  
  8631.  
  8632.  
  8633.  
  8634.  
  8635.  
  8636.  
  8637.  
  8638.  
  8639.                                      142
  8640. fg_sounds (continued)
  8641.  
  8642.  
  8643. Restrictions
  8644.  
  8645.    This routine has no effect if there is asynchronous sound already in
  8646.    progress.  To expand the range of sound effects, Fastgraph temporarily
  8647.    quadruples the clock tick interrupt rate from 18.2 to 72.8 ticks per second
  8648.    while producing asynchronous sound.  Because many disk controllers rely on
  8649.    the 18.2 tick per second clock rate to synchronize disk accesses, your
  8650.    programs should not perform any disk operations when asynchronous sound is
  8651.    in progress.
  8652.  
  8653. See also
  8654.  
  8655.    fg_hush, fg_hushnext, fg_musicb, fg_playing, fg_sound, fg_voice, fg_voices
  8656.  
  8657. Examples
  8658.  
  8659.    13-4
  8660.  
  8661.  
  8662.  
  8663.  
  8664.  
  8665.  
  8666.  
  8667.  
  8668.  
  8669.  
  8670.  
  8671.  
  8672.  
  8673.  
  8674.  
  8675.  
  8676.  
  8677.  
  8678.  
  8679.  
  8680.  
  8681.  
  8682.  
  8683.  
  8684.  
  8685.  
  8686.  
  8687.  
  8688.  
  8689.  
  8690.  
  8691.  
  8692.  
  8693.  
  8694.  
  8695.  
  8696.  
  8697.  
  8698.                                      143
  8699. fg_stall
  8700.  
  8701.  
  8702. Prototype
  8703.  
  8704.    void fg_stall (int delay);
  8705.  
  8706. Description
  8707.  
  8708.    The fg_stall routine delays a program's execution for a given number of
  8709.    processor-specific delay units.  You can use the fg_measure routine to
  8710.    obtain the number of delay units per clock tick for the system being used.
  8711.  
  8712. Parameters
  8713.  
  8714.    delay is the number of delay units to wait.
  8715.  
  8716. Return value
  8717.  
  8718.    none
  8719.  
  8720. Restrictions
  8721.  
  8722.    none
  8723.  
  8724. See also
  8725.  
  8726.    fg_measure, fg_waitfor
  8727.  
  8728. Examples
  8729.  
  8730.    14-3
  8731.  
  8732.  
  8733.  
  8734.  
  8735.  
  8736.  
  8737.  
  8738.  
  8739.  
  8740.  
  8741.  
  8742.  
  8743.  
  8744.  
  8745.  
  8746.  
  8747.  
  8748.  
  8749.  
  8750.  
  8751.  
  8752.  
  8753.  
  8754.  
  8755.  
  8756.  
  8757.                                      144
  8758. fg_swchar
  8759.  
  8760.  
  8761. Prototype
  8762.  
  8763.    void fg_swchar (char *string, int n, int justify);
  8764.  
  8765. Description
  8766.  
  8767.    The fg_swchar routine displays a string of software characters in the
  8768.    current color index.  The string may be left justified, centered, or right
  8769.    justified relative to the graphics cursor.
  8770.  
  8771. Parameters
  8772.  
  8773.    string is the arbitrary-length sequence of characters to display.  It may
  8774.    contain special operators, as summarized in the following table.
  8775.  
  8776.  
  8777.              operator    meaning
  8778.  
  8779.              \           switch to other font
  8780.              \^          superscript the next character
  8781.              \v          subscript the next character
  8782.              _           begin underlining characters until another
  8783.                          underscore character is encountered
  8784.  
  8785.  
  8786.    n is the number of characters in string, including any special operator
  8787.    characters.
  8788.  
  8789.    justify determines how string is positioned relative to the current
  8790.    position.  If justify is negative, string is left justified; if it is zero,
  8791.    string is centered; if it is positive, string is right justified.
  8792.  
  8793. Return value
  8794.  
  8795.    none
  8796.  
  8797. Restrictions
  8798.  
  8799.    Before using this routine, you must use the fg_initw and fg_setworld
  8800.    routines to establish a world space coordinate system.  This routine is not
  8801.    available in Fastgraph/Light and has no effect in text video modes.
  8802.  
  8803. See also
  8804.  
  8805.    fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
  8806.    fg_swlength, fg_swtext
  8807.  
  8808.  
  8809.  
  8810.  
  8811.  
  8812.  
  8813.  
  8814.  
  8815.  
  8816.                                      145
  8817. fg_swchar (continued)
  8818.  
  8819.  
  8820. Examples
  8821.  
  8822.    7-7, 7-8
  8823.  
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.  
  8830.  
  8831.  
  8832.  
  8833.  
  8834.  
  8835.  
  8836.  
  8837.  
  8838.  
  8839.  
  8840.  
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.  
  8849.  
  8850.  
  8851.  
  8852.  
  8853.  
  8854.  
  8855.  
  8856.  
  8857.  
  8858.  
  8859.  
  8860.  
  8861.  
  8862.  
  8863.  
  8864.  
  8865.  
  8866.  
  8867.  
  8868.  
  8869.  
  8870.  
  8871.  
  8872.  
  8873.  
  8874.  
  8875.                                      146
  8876. fg_swlength
  8877.  
  8878.  
  8879. Prototype
  8880.  
  8881.    double fg_swlength (char *string, int n);
  8882.  
  8883. Description
  8884.  
  8885.    The fg_swlength routine computes the length of a string of software
  8886.    characters.
  8887.  
  8888. Parameters
  8889.  
  8890.    string is the arbitrary-length sequence of characters for which to compute
  8891.    the length.  It may contain special operators used by the fg_swchar and
  8892.    fg_swtext routines.
  8893.  
  8894.    n is the number of characters in string, including any special operator
  8895.    characters.
  8896.  
  8897.    justify determines how string is positioned relative to the current
  8898.    position.  If justify is negative, string is left justified; if it is zero,
  8899.    string is centered; if it is positive, string is right justified.
  8900.  
  8901. Return value
  8902.  
  8903.    The length of string, in world space units.
  8904.  
  8905. Restrictions
  8906.  
  8907.    Before using this routine, you must use the fg_initw and fg_setworld
  8908.    routines to establish a world space coordinate system.  This routine is not
  8909.    available in Fastgraph/Light and has no effect in text video modes.
  8910.  
  8911. See also
  8912.  
  8913.    fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
  8914.    fg_swchar, fg_swtext
  8915.  
  8916. Examples
  8917.  
  8918.    7-10
  8919.  
  8920.  
  8921.  
  8922.  
  8923.  
  8924.  
  8925.  
  8926.  
  8927.  
  8928.  
  8929.  
  8930.  
  8931.  
  8932.  
  8933.  
  8934.                                      147
  8935. fg_swtext
  8936.  
  8937.  
  8938. Prototype
  8939.  
  8940.    void fg_swtext (char *string, int n, int justify);
  8941.  
  8942. Description
  8943.  
  8944.    The fg_swtext routine is a scaled down version of the fg_swchar routine.
  8945.    It does not include the alternate font character definitions and thus
  8946.    requires less memory than fg_swchar.
  8947.  
  8948. Parameters
  8949.  
  8950.    string is the arbitrary-length sequence of characters to display.  It may
  8951.    contain special operators, as summarized in the following table.
  8952.  
  8953.  
  8954.              operator    meaning
  8955.  
  8956.              \^          superscript the next character
  8957.              \v          subscript the next character
  8958.              _           begin underlining characters until another
  8959.                          underscore character is encountered
  8960.  
  8961.  
  8962.    n is the number of characters in string, including any special operator
  8963.    characters.
  8964.  
  8965.    justify determines how string is positioned relative to the current
  8966.    position.  If justify is negative, string is left justified; if it is zero,
  8967.    string is centered; if it is positive, string is right justified.
  8968.  
  8969. Return value
  8970.  
  8971.    none
  8972.  
  8973. Restrictions
  8974.  
  8975.    Before using this routine, you must use the fg_initw and fg_setworld
  8976.    routines to establish a world space coordinate system.  This routine is not
  8977.    available in Fastgraph/Light and has no effect in text video modes.
  8978.  
  8979. See also
  8980.  
  8981.    fg_initw, fg_setangle, fg_setratio, fg_setsize, fg_setsizew, fg_setworld,
  8982.    fg_swchar, fg_swlength
  8983.  
  8984.  
  8985.  
  8986.  
  8987.  
  8988.  
  8989.  
  8990.  
  8991.  
  8992.  
  8993.                                      148
  8994. fg_swtext (continued)
  8995.  
  8996.  
  8997. Examples
  8998.  
  8999.    7-9, 7-10
  9000.  
  9001.  
  9002.  
  9003.  
  9004.  
  9005.  
  9006.  
  9007.  
  9008.  
  9009.  
  9010.  
  9011.  
  9012.  
  9013.  
  9014.  
  9015.  
  9016.  
  9017.  
  9018.  
  9019.  
  9020.  
  9021.  
  9022.  
  9023.  
  9024.  
  9025.  
  9026.  
  9027.  
  9028.  
  9029.  
  9030.  
  9031.  
  9032.  
  9033.  
  9034.  
  9035.  
  9036.  
  9037.  
  9038.  
  9039.  
  9040.  
  9041.  
  9042.  
  9043.  
  9044.  
  9045.  
  9046.  
  9047.  
  9048.  
  9049.  
  9050.  
  9051.  
  9052.                                      149
  9053. fg_tcmask
  9054.  
  9055.  
  9056. Prototype
  9057.  
  9058.    void fg_tcmask (int mask);
  9059.  
  9060. Description
  9061.  
  9062.    The fg_tcmask routine defines which color values the fg_tcxfer routine will
  9063.    consider transparent.
  9064.  
  9065. Parameters
  9066.  
  9067.    mask is a 16-bit mask, where each bit indicates whether or not the
  9068.    corresponding color value is transparent.  For example, if bit 0 (the
  9069.    rightmost bit) is 1, then color 0 will be transparent.  If bit 0 is 0,
  9070.    color 0 will not be transparent.  Because the mask size is 16 bits, only
  9071.    the first 16 color values may be defined as transparent.
  9072.  
  9073. Return value
  9074.  
  9075.    none
  9076.  
  9077. Restrictions
  9078.  
  9079.    This routine has no effect in text video modes.
  9080.  
  9081. See also
  9082.  
  9083.    fg_tcxfer
  9084.  
  9085. Examples
  9086.  
  9087.    9-26
  9088.  
  9089.  
  9090.  
  9091.  
  9092.  
  9093.  
  9094.  
  9095.  
  9096.  
  9097.  
  9098.  
  9099.  
  9100.  
  9101.  
  9102.  
  9103.  
  9104.  
  9105.  
  9106.  
  9107.  
  9108.  
  9109.  
  9110.  
  9111.                                      150
  9112. fg_tcxfer
  9113.  
  9114.  
  9115. Prototype
  9116.  
  9117.    void fg_tcxfer (int minx, int maxx, int miny, int maxy, int newx, int newy,
  9118.      int source_page, int dest_page);
  9119.  
  9120. Description
  9121.  
  9122.    The fg_tcxfer routine copies a rectangular region from any position on any
  9123.    video page to any position on any video page, excluding any pixels whose
  9124.    color is transparent.  The transparent colors are defined by the fg_tcmask
  9125.    routine.
  9126.  
  9127. Parameters
  9128.  
  9129.    minx is the x coordinate of the source region's left edge.  Its value is
  9130.    reduced to a byte boundary if necessary.
  9131.  
  9132.    maxx is the x coordinate of the source region's right edge.  It must be
  9133.    greater than or equal to the value of minx.  Its value is extended to a
  9134.    byte boundary if necessary.
  9135.  
  9136.    miny is the y coordinate of the source region's top edge.
  9137.  
  9138.    maxy is the y coordinate of the source region's bottom edge.  It must be
  9139.    greater than or equal to the value of miny.
  9140.  
  9141.    newx is the x coordinate of the destination region's left edge.
  9142.  
  9143.    newy is the y coordinate of the destination region's bottom edge.
  9144.  
  9145.    source_page is the video page number containing the source region.
  9146.  
  9147.    dest_page is the video page number for the destination region.
  9148.  
  9149. Return value
  9150.  
  9151.    none
  9152.  
  9153. Restrictions
  9154.  
  9155.    If source_page and dest_page reference the same video page, the source
  9156.    region and destination region must not overlap.  This routine has no effect
  9157.    in text video modes.
  9158.  
  9159.  
  9160.  
  9161.  
  9162.  
  9163.  
  9164.  
  9165.  
  9166.  
  9167.  
  9168.  
  9169.  
  9170.                                      151
  9171. fg_tcxfer (continued)
  9172.  
  9173.  
  9174. See also
  9175.  
  9176.    fg_tcmask, fg_transfer
  9177.  
  9178. Examples
  9179.  
  9180.    9-26
  9181.  
  9182.  
  9183.  
  9184.  
  9185.  
  9186.  
  9187.  
  9188.  
  9189.  
  9190.  
  9191.  
  9192.  
  9193.  
  9194.  
  9195.  
  9196.  
  9197.  
  9198.  
  9199.  
  9200.  
  9201.  
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.  
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.  
  9221.  
  9222.  
  9223.  
  9224.  
  9225.  
  9226.  
  9227.  
  9228.  
  9229.                                      152
  9230. fg_testmode
  9231.  
  9232.  
  9233. Prototype
  9234.  
  9235.    int fg_testmode (int mode, int pages);
  9236.  
  9237. Description
  9238.  
  9239.    The fg_testmode routine determines whether or not a specified video mode is
  9240.    available on the user's system.  Additionally, fg_testmode can check if
  9241.    there is enough video memory (for physical pages) or random-access memory
  9242.    (for virtual pages) to support the number of video pages needed.
  9243.  
  9244. Parameters
  9245.  
  9246.    mode is the video mode number to test, between 0 and 21.  Refer to the
  9247.    description of the fg_setmode routine for a list of available video modes.
  9248.  
  9249.    pages is the number of video pages required (either physical pages, virtual
  9250.    pages, or both).  If the pages parameter is zero or negative, fg_testmode
  9251.    checks for availability of the video mode but does not consider video
  9252.    memory requirements.
  9253.  
  9254. Return value
  9255.  
  9256.    If the requested video mode is available (with the requested number of
  9257.    video pages), fg_testmode returns 1.  If not, it returns 0.
  9258.  
  9259. Restrictions
  9260.  
  9261.    none
  9262.  
  9263. See also
  9264.  
  9265.    fg_automode, fg_bestmode, fg_setmode
  9266.  
  9267. Examples
  9268.  
  9269.    3-3, 3-8, 5-14, 6-7
  9270.  
  9271.  
  9272.  
  9273.  
  9274.  
  9275.  
  9276.  
  9277.  
  9278.  
  9279.  
  9280.  
  9281.  
  9282.  
  9283.  
  9284.  
  9285.  
  9286.  
  9287.  
  9288.                                      153
  9289. fg_text
  9290.  
  9291.  
  9292. Prototype
  9293.  
  9294.    void fg_text (char *string, int n);
  9295.  
  9296. Description
  9297.  
  9298.    The fg_text routine displays a string of hardware characters, starting at
  9299.    the text cursor position, using the current text attribute (for text modes)
  9300.    or color index (for graphics modes).  This routine leaves the text cursor
  9301.    one column to the right of the last character changed (or the first column
  9302.    of the next row if the last character is at the end of a row).
  9303.  
  9304. Parameters
  9305.  
  9306.    string is the arbitrary-length sequence of characters to display.
  9307.  
  9308.    n is the number of characters to display from string.
  9309.  
  9310. Return value
  9311.  
  9312.    none
  9313.  
  9314. Restrictions
  9315.  
  9316.    none
  9317.  
  9318. See also
  9319.  
  9320.    fg_locate
  9321.  
  9322. Examples
  9323.  
  9324.    7-1 to 7-7, 7-9, 7-10
  9325.  
  9326.  
  9327.  
  9328.  
  9329.  
  9330.  
  9331.  
  9332.  
  9333.  
  9334.  
  9335.  
  9336.  
  9337.  
  9338.  
  9339.  
  9340.  
  9341.  
  9342.  
  9343.  
  9344.  
  9345.  
  9346.  
  9347.                                      154
  9348. fg_transfer
  9349.  
  9350.  
  9351. Prototype
  9352.  
  9353.    void fg_transfer (int minx, int maxx, int miny, int maxy, int newx, int
  9354.    newy,
  9355.      int source_page, int dest_page);
  9356.  
  9357. Description
  9358.  
  9359.    The fg_transfer routine copies a rectangular region from any position on
  9360.    any video page to any position on any video page.  In text modes, the
  9361.    region is defined in character space; in graphics modes, it is defined in
  9362.    screen space.  It is Fastgraph's most general image transfer routine.
  9363.  
  9364. Parameters
  9365.  
  9366.    minx is the x coordinate of the source region's left edge.  In graphics
  9367.    modes, its value is reduced to a byte boundary if necessary.
  9368.  
  9369.    maxx is the x coordinate of the source region's right edge.  It must be
  9370.    greater than or equal to the value of minx.  In graphics modes, its value
  9371.    is extended to a byte boundary if necessary.
  9372.  
  9373.    miny is the y coordinate of the source region's top edge.
  9374.  
  9375.    maxy is the y coordinate of the source region's bottom edge.  It must be
  9376.    greater than or equal to the value of miny.
  9377.  
  9378.    newx is the x coordinate of the destination region's left edge.
  9379.  
  9380.    newy is the y coordinate of the destination region's bottom edge.
  9381.  
  9382.    source_page is the video page number containing the source region.
  9383.  
  9384.    dest_page is the video page number for the destination region.
  9385.  
  9386. Return value
  9387.  
  9388.    none
  9389.  
  9390. Restrictions
  9391.  
  9392.    If source_page and dest_page reference the same video page, the source
  9393.    region and destination region must not overlap.
  9394.  
  9395.  
  9396.  
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.                                      155
  9407. fg_transfer (continued)
  9408.  
  9409.  
  9410. See also
  9411.  
  9412.    fg_restore, fg_restorew, fg_save, fg_savew, fg_tcxfer
  9413.  
  9414. Examples
  9415.  
  9416.    9-23, 9-24, 9-25, 10-4, 10-5
  9417.  
  9418.  
  9419.  
  9420.  
  9421.  
  9422.  
  9423.  
  9424.  
  9425.  
  9426.  
  9427.  
  9428.  
  9429.  
  9430.  
  9431.  
  9432.  
  9433.  
  9434.  
  9435.  
  9436.  
  9437.  
  9438.  
  9439.  
  9440.  
  9441.  
  9442.  
  9443.  
  9444.  
  9445.  
  9446.  
  9447.  
  9448.  
  9449.  
  9450.  
  9451.  
  9452.  
  9453.  
  9454.  
  9455.  
  9456.  
  9457.  
  9458.  
  9459.  
  9460.  
  9461.  
  9462.  
  9463.  
  9464.  
  9465.                                      156
  9466. fg_version
  9467.  
  9468.  
  9469. Prototype
  9470.  
  9471.    void fg_version (int *major, int *minor);
  9472.  
  9473. Description
  9474.  
  9475.    The fg_version routine returns the major and minor version numbers for your
  9476.    copy of Fastgraph or Fastgraph/Light.  For example, if you are using
  9477.    Fastgraph version 2.0, the major version number is 2 and the minor version
  9478.    number is 0.
  9479.  
  9480. Parameters
  9481.  
  9482.    major receives the major version number.
  9483.  
  9484.    minor receives the minor version number, expressed in hundredths.
  9485.  
  9486. Return value
  9487.  
  9488.    none
  9489.  
  9490. Restrictions
  9491.  
  9492.    none
  9493.  
  9494. Examples
  9495.  
  9496.    1-1, 1-2, 1-3
  9497.  
  9498.  
  9499.  
  9500.  
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.  
  9509.  
  9510.  
  9511.  
  9512.  
  9513.  
  9514.  
  9515.  
  9516.  
  9517.  
  9518.  
  9519.  
  9520.  
  9521.  
  9522.  
  9523.  
  9524.                                      157
  9525. fg_voice
  9526.  
  9527.  
  9528. Prototype
  9529.  
  9530.    void fg_voice (int channel, int frequency, int volume, int duration);
  9531.  
  9532. Description
  9533.  
  9534.    The fg_voice routine produces a tone of a specified frequency, duration,
  9535.    and volume using one of the TI sound chip's four independent voice
  9536.    channels.
  9537.  
  9538. Parameters
  9539.  
  9540.    channel defines the voice channel or type of noise, as shown below.
  9541.  
  9542.  
  9543.                   value   meaning
  9544.  
  9545.                     1     voice channel #1
  9546.                     2     voice channel #2
  9547.                     3     voice channel #3
  9548.                     4     voice channel #4, periodic noise
  9549.                     5     voice channel #4, white noise
  9550.  
  9551.  
  9552.  
  9553.    frequency defines the tone's frequency in Hertz.  If channel is 1, 2, or 3,
  9554.    then frequency represents the actual frequency, between 18 and 32,767.  If
  9555.    channel is 4 or 5, frequency is instead a value that represents a specific
  9556.    frequency, as shown below.
  9557.  
  9558.  
  9559.                           value  frequency
  9560.  
  9561.                             0     512 Hertz
  9562.                             1    1024 Hertz
  9563.                             2    2048 Hertz
  9564.  
  9565.  
  9566.    volume is the tone's volume, between 0 (silent) and 15 (loudest).
  9567.  
  9568.    duration is the tone's length in clock ticks (there are approximately 18.2
  9569.    clock ticks per second).  If duration is zero or negative, the tone is said
  9570.    to be continuous and will play until you stop it with the fg_quiet routine.
  9571.  
  9572.  
  9573. Return value
  9574.  
  9575.    none
  9576.  
  9577. Restrictions
  9578.  
  9579.    This routine should only be used on systems equipped with the TI sound chip
  9580.    (namely, the PCjr and Tandy 1000 systems).  It has no effect if there is
  9581.    asynchronous sound already in progress.
  9582.  
  9583.                                      158
  9584. fg_voice (continued)
  9585.  
  9586.  
  9587. See also
  9588.  
  9589.    fg_music, fg_quiet, fg_sound, fg_voices
  9590.  
  9591. Examples
  9592.  
  9593.    13-2
  9594.  
  9595.  
  9596.  
  9597.  
  9598.  
  9599.  
  9600.  
  9601.  
  9602.  
  9603.  
  9604.  
  9605.  
  9606.  
  9607.  
  9608.  
  9609.  
  9610.  
  9611.  
  9612.  
  9613.  
  9614.  
  9615.  
  9616.  
  9617.  
  9618.  
  9619.  
  9620.  
  9621.  
  9622.  
  9623.  
  9624.  
  9625.  
  9626.  
  9627.  
  9628.  
  9629.  
  9630.  
  9631.  
  9632.  
  9633.  
  9634.  
  9635.  
  9636.  
  9637.  
  9638.  
  9639.  
  9640.  
  9641.  
  9642.                                      159
  9643. fg_voices
  9644.  
  9645.  
  9646. Prototype
  9647.  
  9648.    void fg_voices (int *sound_array, int ntimes);
  9649.  
  9650. Description
  9651.  
  9652.    The fg_voices routine uses the TI sound chip to play a series of tones of
  9653.    specified frequencies, durations, and volumes, concurrent with other
  9654.    activity.  It is the asynchronous version of the fg_voice routine.
  9655.  
  9656. Parameters
  9657.  
  9658.    sound_array is an arbitrary-length array containing a series of
  9659.    (channel,frequency,volume,duration) sound definitions.  The format of this
  9660.    array is:
  9661.  
  9662.  
  9663.                           [0]    channel # of sound 1
  9664.  
  9665.                           [1]    frequency of sound 1
  9666.  
  9667.                           [2]    volume    of sound 1
  9668.  
  9669.                           [3]    duration  of sound 1
  9670.                            .
  9671.                            .
  9672.                            .
  9673.  
  9674.                        [4n-4]    channel # of sound n
  9675.  
  9676.                        [4n-3]    frequency of sound n
  9677.  
  9678.                        [4n-2]    volume    of sound n
  9679.  
  9680.                        [4n-1]    duration  of sound n
  9681.  
  9682.                          [4n]       terminator (0)
  9683.  
  9684.  
  9685.    The channel numbers, frequencies, volumes, and durations must be in the
  9686.    same ranges as discussed in the description of the fg_voice routine, except
  9687.    the durations are quadrupled because of the accelerated clock tick
  9688.    interrupt rate (there are 72.8 instead of 18.2 clock ticks per second).  A
  9689.    null character (that is, a zero byte) terminates the array.
  9690.  
  9691.    ntimes specifies the number of times to cycle through the sounds defined in
  9692.    sound_array.  If ntimes is negative, the sounds will play repetitively
  9693.    until stopped with the fg_hush or fg_hushnext routine.
  9694.  
  9695.  
  9696.  
  9697.  
  9698.  
  9699.  
  9700.  
  9701.                                      160
  9702. fg_voices (continued)
  9703.  
  9704.  
  9705. Return value
  9706.  
  9707.    none
  9708.  
  9709. Restrictions
  9710.  
  9711.    This routine should only be used on systems equipped with the TI sound chip
  9712.    (namely, the PCjr and Tandy 1000 systems).  It has no effect if there is
  9713.    asynchronous sound already in progress.  To expand the range of sound
  9714.    effects, Fastgraph temporarily quadruples the clock tick interrupt rate
  9715.    from 18.2 to 72.8 ticks per second while producing asynchronous sound.
  9716.    Because many disk controllers rely on the 18.2 tick per second clock rate
  9717.    to synchronize disk accesses, your programs should not perform any disk
  9718.    operations when asynchronous sound is in progress.
  9719.  
  9720. See also
  9721.  
  9722.    fg_hush, fg_hushnext, fg_musicb, fg_playing, fg_sounds, fg_voice
  9723.  
  9724. Examples
  9725.  
  9726.    13-5
  9727.  
  9728.  
  9729.  
  9730.  
  9731.  
  9732.  
  9733.  
  9734.  
  9735.  
  9736.  
  9737.  
  9738.  
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.  
  9747.  
  9748.  
  9749.  
  9750.  
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.  
  9757.  
  9758.  
  9759.  
  9760.                                      161
  9761. fg_waitfor
  9762.  
  9763.  
  9764. Prototype
  9765.  
  9766.    void fg_waitfor (int ticks);
  9767.  
  9768. Description
  9769.  
  9770.    The fg_waitfor routine delays a program's execution for a given number of
  9771.    clock ticks.  There are 18.2 clock ticks per second, regardless of the
  9772.    system's processor speed.
  9773.  
  9774. Parameters
  9775.  
  9776.    ticks is the number of clock ticks to wait.
  9777.  
  9778. Return value
  9779.  
  9780.    none
  9781.  
  9782. Restrictions
  9783.  
  9784.    none
  9785.  
  9786. See also
  9787.  
  9788.    fg_stall
  9789.  
  9790. Examples
  9791.  
  9792.    5-11, 10-1 to 10-5, 11-5, 11-6, 12-2, 12-6, 12-7, 12-11, 12-12, 13-1, 13-2,
  9793.    13-3, 13-6, 13-7, 14-1
  9794.  
  9795.  
  9796.  
  9797.  
  9798.  
  9799.  
  9800.  
  9801.  
  9802.  
  9803.  
  9804.  
  9805.  
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.                                      162
  9820. fg_waitkey
  9821.  
  9822.  
  9823. Prototype
  9824.  
  9825.    void fg_waitkey (void);
  9826.  
  9827. Description
  9828.  
  9829.    The fg_waitkey routine flushes the BIOS keyboard buffer (that is, removes
  9830.    any type-ahead characters) and then waits for another keystroke.  It is
  9831.    most useful in "press any key to continue" situations.
  9832.  
  9833. Parameters
  9834.  
  9835.    none
  9836.  
  9837. Return value
  9838.  
  9839.    none
  9840.  
  9841. Restrictions
  9842.  
  9843.    none
  9844.  
  9845. See also
  9846.  
  9847.    fg_getkey, fg_intkey
  9848.  
  9849. Examples
  9850.  
  9851.    3-2 to 3-8
  9852.  
  9853.  
  9854.  
  9855.  
  9856.  
  9857.  
  9858.  
  9859.  
  9860.  
  9861.  
  9862.  
  9863.  
  9864.  
  9865.  
  9866.  
  9867.  
  9868.  
  9869.  
  9870.  
  9871.  
  9872.  
  9873.  
  9874.  
  9875.  
  9876.  
  9877.  
  9878.                                      163
  9879. fg_where
  9880.  
  9881.  
  9882. Prototype
  9883.  
  9884.    void fg_where (int *row, int *column);
  9885.  
  9886. Description
  9887.  
  9888.    The fg_where routine retrieves the text cursor position for the active
  9889.    display page.
  9890.  
  9891. Parameters
  9892.  
  9893.    row receives the text cursor's current row number, between 0 and 24 (0 and
  9894.    29 for VGA graphics modes 17 and 18).
  9895.  
  9896.    column receives text cursor's current column number, between 0 and 39 for
  9897.    40-column modes, or between 0 and 79 for 80-column modes.
  9898.  
  9899. Return value
  9900.  
  9901.    none
  9902.  
  9903. Restrictions
  9904.  
  9905.    none
  9906.  
  9907. See also
  9908.  
  9909.    fg_locate
  9910.  
  9911. Examples
  9912.  
  9913.    7-2
  9914.  
  9915.  
  9916.  
  9917.  
  9918.  
  9919.  
  9920.  
  9921.  
  9922.  
  9923.  
  9924.  
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  
  9931.  
  9932.  
  9933.  
  9934.  
  9935.  
  9936.  
  9937.                                      164
  9938. fg_xalpha
  9939.  
  9940.  
  9941. Prototype
  9942.  
  9943.    int fg_xalpha (int ix);
  9944.  
  9945. Description
  9946.  
  9947.    The fg_xalpha routine translates a screen space x coordinate to the
  9948.    character space column containing that coordinate.
  9949.  
  9950. Parameters
  9951.  
  9952.    ix is the screen space coordinate to translate.
  9953.  
  9954. Return value
  9955.  
  9956.    The character space column containing the screen space coordinate ix.  In
  9957.    text modes, the return value is equal to the value of ix.
  9958.  
  9959. Restrictions
  9960.  
  9961.    none
  9962.  
  9963. See also
  9964.  
  9965.    fg_xconvert, fg_yalpha, fg_yconvert
  9966.  
  9967. Examples
  9968.  
  9969.    12-9
  9970.  
  9971.  
  9972.  
  9973.  
  9974.  
  9975.  
  9976.  
  9977.  
  9978.  
  9979.  
  9980.  
  9981.  
  9982.  
  9983.  
  9984.  
  9985.  
  9986.  
  9987.  
  9988.  
  9989.  
  9990.  
  9991.  
  9992.  
  9993.  
  9994.  
  9995.  
  9996.                                      165
  9997. fg_xconvert
  9998.  
  9999.  
  10000. Prototype
  10001.  
  10002.    int fg_xconvert (int column);
  10003.  
  10004. Description
  10005.  
  10006.    The fg_xconvert routine translates a character space column to the screen
  10007.    space coordinate of its leftmost pixel.  In graphics video modes,
  10008.    fg_xconvert(1) is an easy way to determine the width in pixels of a
  10009.    character cell.
  10010.  
  10011. Parameters
  10012.  
  10013.    column is the character space column to translate.
  10014.  
  10015. Return value
  10016.  
  10017.    The screen space x coordinate of the leftmost pixel in the character space
  10018.    column column.  In text modes, the return value is equal to the value of
  10019.    column.
  10020.  
  10021. Restrictions
  10022.  
  10023.    none
  10024.  
  10025. See also
  10026.  
  10027.    fg_xalpha, fg_yalpha, fg_yconvert
  10028.  
  10029. Examples
  10030.  
  10031.    7-6, 12-7
  10032.  
  10033.  
  10034.  
  10035.  
  10036.  
  10037.  
  10038.  
  10039.  
  10040.  
  10041.  
  10042.  
  10043.  
  10044.  
  10045.  
  10046.  
  10047.  
  10048.  
  10049.  
  10050.  
  10051.  
  10052.  
  10053.  
  10054.  
  10055.                                      166
  10056. fg_xscreen
  10057.  
  10058.  
  10059. Prototype
  10060.  
  10061.    int fg_xscreen (double x);
  10062.  
  10063. Description
  10064.  
  10065.    The fg_xscreen routine translates a world space x coordinate to its screen
  10066.    space equivalent.
  10067.  
  10068. Parameters
  10069.  
  10070.    x is the world space coordinate to translate.
  10071.  
  10072. Return value
  10073.  
  10074.    The screen space x coordinate equivalent to the world space coordinate x.
  10075.  
  10076. Restrictions
  10077.  
  10078.    This routine is not available in Fastgraph/Light.
  10079.  
  10080. See also
  10081.  
  10082.    fg_xworld, fg_yscreen, fg_yworld
  10083.  
  10084.  
  10085.  
  10086.  
  10087.  
  10088.  
  10089.  
  10090.  
  10091.  
  10092.  
  10093.  
  10094.  
  10095.  
  10096.  
  10097.  
  10098.  
  10099.  
  10100.  
  10101.  
  10102.  
  10103.  
  10104.  
  10105.  
  10106.  
  10107.  
  10108.  
  10109.  
  10110.  
  10111.  
  10112.  
  10113.  
  10114.                                      167
  10115. fg_xworld
  10116.  
  10117.  
  10118. Prototype
  10119.  
  10120.    double fg_xworld (int ix);
  10121.  
  10122. Description
  10123.  
  10124.    The fg_xworld routine translates a screen space x coordinate to its world
  10125.    space equivalent.
  10126.  
  10127. Parameters
  10128.  
  10129.    ix is the screen space coordinate to translate.
  10130.  
  10131. Return value
  10132.  
  10133.    The world space x coordinate equivalent to the screen space coordinate ix.
  10134.  
  10135. Restrictions
  10136.  
  10137.    This routine is not available in Fastgraph/Light.
  10138.  
  10139. See also
  10140.  
  10141.    fg_xscreen, fg_yscreen, fg_yworld
  10142.  
  10143.  
  10144.  
  10145.  
  10146.  
  10147.  
  10148.  
  10149.  
  10150.  
  10151.  
  10152.  
  10153.  
  10154.  
  10155.  
  10156.  
  10157.  
  10158.  
  10159.  
  10160.  
  10161.  
  10162.  
  10163.  
  10164.  
  10165.  
  10166.  
  10167.  
  10168.  
  10169.  
  10170.  
  10171.  
  10172.  
  10173.                                      168
  10174. fg_yalpha
  10175.  
  10176.  
  10177. Prototype
  10178.  
  10179.    int fg_yalpha (int iy);
  10180.  
  10181. Description
  10182.  
  10183.    The fg_yalpha routine translates a screen space y coordinate to the
  10184.    character space row containing that coordinate.
  10185.  
  10186. Parameters
  10187.  
  10188.    iy is the screen space coordinate to translate.
  10189.  
  10190. Return value
  10191.  
  10192.    The character space row containing the screen space coordinate iy.  In text
  10193.    modes, the return value is equal to the value of iy.
  10194.  
  10195. Restrictions
  10196.  
  10197.    none
  10198.  
  10199. See also
  10200.  
  10201.    fg_xalpha, fg_xconvert, fg_yconvert
  10202.  
  10203. Examples
  10204.  
  10205.    12-9
  10206.  
  10207.  
  10208.  
  10209.  
  10210.  
  10211.  
  10212.  
  10213.  
  10214.  
  10215.  
  10216.  
  10217.  
  10218.  
  10219.  
  10220.  
  10221.  
  10222.  
  10223.  
  10224.  
  10225.  
  10226.  
  10227.  
  10228.  
  10229.  
  10230.  
  10231.  
  10232.                                      169
  10233. fg_yconvert
  10234.  
  10235.  
  10236. Prototype
  10237.  
  10238.    int fg_yconvert (int row);
  10239.  
  10240. Description
  10241.  
  10242.    The fg_yconvert routine translates a character space row to the screen
  10243.    space coordinate of its top (lowest-numbered) pixel.  In graphics video
  10244.    modes, fg_yconvert(1) is an easy way to determine the height in pixels of a
  10245.    character cell.
  10246.  
  10247. Parameters
  10248.  
  10249.    row is the character space row to translate.
  10250.  
  10251. Return value
  10252.  
  10253.    The screen space y coordinate of the top pixel in the character space row
  10254.    row.  In text modes, the return value is equal to the value of row.
  10255.  
  10256. Restrictions
  10257.  
  10258.    none
  10259.  
  10260. See also
  10261.  
  10262.    fg_xalpha, fg_xconvert, fg_yalpha
  10263.  
  10264. Examples
  10265.  
  10266.    7-6, 12-7
  10267.  
  10268.  
  10269.  
  10270.  
  10271.  
  10272.  
  10273.  
  10274.  
  10275.  
  10276.  
  10277.  
  10278.  
  10279.  
  10280.  
  10281.  
  10282.  
  10283.  
  10284.  
  10285.  
  10286.  
  10287.  
  10288.  
  10289.  
  10290.  
  10291.                                      170
  10292. fg_yscreen
  10293.  
  10294.  
  10295. Prototype
  10296.  
  10297.    int fg_yscreen (double y);
  10298.  
  10299. Description
  10300.  
  10301.    The fg_yscreen routine translates a world space y coordinate to its screen
  10302.    space equivalent.
  10303.  
  10304. Parameters
  10305.  
  10306.    y is the world space coordinate to translate.
  10307.  
  10308. Return value
  10309.  
  10310.    The screen space y coordinate equivalent to the world space coordinate y.
  10311.  
  10312. Restrictions
  10313.  
  10314.    This routine is not available in Fastgraph/Light.
  10315.  
  10316. See also
  10317.  
  10318.    fg_xscreen, fg_xworld, fg_yworld
  10319.  
  10320.  
  10321.  
  10322.  
  10323.  
  10324.  
  10325.  
  10326.  
  10327.  
  10328.  
  10329.  
  10330.  
  10331.  
  10332.  
  10333.  
  10334.  
  10335.  
  10336.  
  10337.  
  10338.  
  10339.  
  10340.  
  10341.  
  10342.  
  10343.  
  10344.  
  10345.  
  10346.  
  10347.  
  10348.  
  10349.  
  10350.                                      171
  10351. fg_yworld
  10352.  
  10353.  
  10354. Prototype
  10355.  
  10356.    double fg_yworld (int iy);
  10357.  
  10358. Description
  10359.  
  10360.    The fg_yworld routine translates a screen space y coordinate to its world
  10361.    space equivalent.
  10362.  
  10363. Parameters
  10364.  
  10365.    iy is the screen space coordinate to translate.
  10366.  
  10367. Return value
  10368.  
  10369.    The world space y coordinate equivalent to the screen space coordinate iy.
  10370.  
  10371. Restrictions
  10372.  
  10373.    This routine is not available in Fastgraph/Light.
  10374.  
  10375. See also
  10376.  
  10377.    fg_xscreen, fg_xworld, fg_yscreen
  10378.  
  10379.  
  10380.  
  10381.  
  10382.  
  10383.  
  10384.  
  10385.  
  10386.  
  10387.  
  10388.  
  10389.  
  10390.  
  10391.  
  10392.  
  10393.  
  10394.  
  10395.  
  10396.  
  10397.  
  10398.  
  10399.  
  10400.  
  10401.  
  10402.  
  10403.  
  10404.  
  10405.  
  10406.  
  10407.  
  10408.  
  10409.                                      172
  10410.